zhongwei/gh-edspencer-claude-agents-plugins-product-team
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-29 18:24:52 +08:00
commit 737328c2bd
37 changed files with 6287 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
commands/add-to-test-plan.md Normal file
View File

@@ -0,0 +1,21 @@
---
allowed-tools: Bash, Edit, Grep, Read, WebSearch, WebFetch, Write(PLAN.md)
argument-hint: [test-file]
description: Adds tests from a specific test file into our ongoing test plan
---
# Add Tests to UI Test Plan
You are tasked with maintaining our UI test plan located at ./test/integration/TEST-PLAN.md.
Your task is to add tests from the provided test file ($1) into the existing UI test plan. When adding tests:
1. **Review the existing test plan** to understand current test coverage
2. **Extract relevant tests** from the source test file ($1)
3. **Avoid duplicates** - don't add tests that already exist in the plan
4. **Merge intelligently** - combine similar tests rather than duplicating them
5. **Maintain organization** - keep tests grouped by category/feature
6. **Update test results** section if the source file contains test execution results
7. **Add to "Known Issues"** section if any issues are documented in the source
The run-integration-tests SlashCommand will be used separately to run these tests via the Playwright test runner.

100
commands/agentic-create-plan.md Normal file
View File

@@ -0,0 +1,100 @@
---
allowed-tools: Bash, Edit, Grep, Read, WebSearch, WebFetch, Write
argument-hint: [spec-file] [instructions]
description: Fully create a plan using sub agents, including comprehensive review and revision
---
## Task: Use sub agents to create an entire plan from start to finish
You will make extensive use of the following sub-agents:
@plan-writer - Use this agent to create the plan
@plan-checker - Use this agent to review and revise the plan
The sub-agents have specialized knowledge and abilities, but also, delegating to them allows you to use less of your LLM context on solving issues, as you are playing an orchestrator role. Try to delegate to these sub-agents as much as possible.
## Process
1. Read the entire SPEC.md file for the task at hand (unless you were just given a text description of the specification)
2. Ask the plan writer agent to create a plan for the task at hand.
3. Ask the plan checker agent to review and revise the plan.
4. If the plan checker agent asks you to make changes to the plan, make those changes
5. **Sync plan files to GitHub**: If working with a GitHub issue (task directory named `{issue-number}-{task-name}`), use the github-task-sync skill to push all plan files (PLAN.md, TEST_PLAN.md, COMMIT_MESSAGE.md) to the GitHub issue
Once you are done, please report back with the status of the plan.
## Critical File Management Instructions
**IMPORTANT:** The plan creation process should produce THREE FILES: `PLAN.md`, `TEST_PLAN.md`, and `COMMIT_MESSAGE.md`
**When delegating to sub-agents, explicitly instruct them:**
- The plan-writer agent will create PLAN.md, TEST_PLAN.md, and COMMIT_MESSAGE.md as part of the planning phase
- Make all refinements directly within PLAN.md and TEST_PLAN.md rather than creating support documents
- Do NOT create additional files such as:
- VALIDATION-REPORT.md
- IMPLEMENTATION-NOTES.md
- REVIEW-SUMMARY.md
- QUICK-REFERENCE.md
- IMPROVEMENTS-SUMMARY.md
- Or any other support documents
- Include any validation findings, implementation notes, or review feedback directly in the appropriate sections of PLAN.md
- All architectural decisions and technical details belong in PLAN.md, not separate files
**Rationale:**
- Keeps task directories clean and focused on core deliverables
- Users expect PLAN.md, TEST_PLAN.md, and COMMIT_MESSAGE.md as standard outputs
- COMMIT_MESSAGE.md provides a draft commit message that can be verified/updated at completion
- Easier to version control and track changes
- Reduces cognitive load for developers following the plan
- Simplifies onboarding (fewer files to read)
## Instructions
- If, during investigation and creation of the plan, it becomes clear that the specification was not possible, immediately stop what you're doing and ask the user for how to proceed.
## GitHub Sync Instructions
When working with a GitHub issue:
1. **Detect GitHub Issue**: Check if the task directory follows the pattern `tasks/{issue-number}-{task-name}/` (e.g., `tasks/196-team-page/`)
2. **Extract Issue Number**: Parse the issue number from the directory name
3. **Create Status Summary**: After plan-checker validation is complete, create a 2-paragraph summary of what the implementation plan covers (NOT a summary of the process that created it)
4. **Push Plan to GitHub**: Use `push-file.sh` to sync with status summary:
```bash
~/.claude/plugins/marketplaces/edspencer-agents/plugins/product-team/skills/github-task-sync/push-file.sh {issue-number} PLAN {status-file} PLAN.md
```
5. **Push Other Files**: Use `push.sh` to sync TEST_PLAN.md and COMMIT_MESSAGE.md:
```bash
~/.claude/plugins/marketplaces/edspencer-agents/plugins/product-team/skills/github-task-sync/push.sh {issue-number} {task-directory}
```
**Status Summary Format:**
The status summary should be a 2-paragraph overview describing WHAT the plan will implement:
```markdown
**Status:** Complete
The implementation plan uses a phased approach to build [feature description] over [timeline]. It begins with [initial phases], progresses through [middle phases], and concludes with [final phases].
Key phases include: (1) [Phase 1 description], (2) [Phase 2 description], (3) [Phase 3 description], and (4) [Final phase]. Each phase builds on previous work with clear dependencies and success criteria.
- Key phase 1 (optional bullet points)
- Key phase 2
- Key phase 3
```
**Example:**
```bash
# After creating 2-paragraph status summary
~/.claude/plugins/marketplaces/edspencer-agents/plugins/product-team/skills/github-task-sync/push-file.sh 196 PLAN plan-status.txt ./tasks/196-team-page/PLAN.md
~/.claude/plugins/marketplaces/edspencer-agents/plugins/product-team/skills/github-task-sync/push.sh 196 ./tasks/196-team-page
```
This creates/updates the PLAN comment on GitHub with:
- Heading: "Implementation Plan:"
- Status summary visible at top
- Full plan content in collapsible `<details>` section
- TEST_PLAN.md and COMMIT_MESSAGE.md as separate collapsible comments
**Reference:** See `~/.claude/plugins/marketplaces/edspencer-agents/plugins/product-team/skills/github-task-sync/SKILL.md` for complete documentation.

88
commands/agentic-create-spec.md Normal file
View File

@@ -0,0 +1,88 @@
---
allowed-tools: Bash, Edit, Grep, Read, WebSearch, WebFetch, Write
argument-hint: [instructions]
description: Fully create a spec using sub agents, including comprehensive review and revision
---
## Task: Use sub agents to create an entire spec from start to finish
You will make extensive use of the following sub-agents:
@spec-writer - Use this agent to create the spec
@spec-checker - Use this agent to review and revise the spec
The sub-agents have specialized knowledge and abilities, but also, delegating to them allows you to use less of your LLM context on solving issues, as you are playing an orchestrator role. Try to delegate to these sub-agents as much as possible.
## Process
1. Ask the spec writer agent to create a spec for the task at hand.
2. Ask the spec checker agent to review and revise the spec.
3. If the spec checker agent asks you to make changes to the spec, make those changes
4. **Sync SPEC.md to GitHub**: If working with a GitHub issue (task directory named `{issue-number}-{task-name}`), use the github-task-sync skill to push the completed SPEC.md to the GitHub issue as a collapsible comment
5. Once you are done, please report back with the status of the spec.
## Critical File Management Instructions
**IMPORTANT:** The spec creation process should produce ONLY ONE FILE: `SPEC.md`
**When delegating to sub-agents, explicitly instruct them:**
- Make all refinements directly within SPEC.md rather than creating new support documents
- Do NOT create additional files such as:
- VALIDATION-REPORT.md
- QUICK-REFERENCE.md
- IMPROVEMENTS-SUMMARY.md
- REVIEW-NOTES.md
- Or any other support documents
- Include any review notes, validation findings, or improvement suggestions as inline comments or in a "Review Summary" section at the end of SPEC.md
- All feedback and refinements must be incorporated directly into the SPEC.md content
**Rationale:**
- Keeps task directories clean and focused on core deliverables
- Users expect only SPEC.md as the output
- Easier to version control and track changes
- Reduces cognitive load for developers reading the spec
## Instructions
- If, during investigation and creation of the spec, it becomes clear that the specification was not possible, immediately stop what you're doing and ask the user for how to proceed.
## GitHub Sync Instructions
When working with a GitHub issue:
1. **Detect GitHub Issue**: Check if the task directory follows the pattern `tasks/{issue-number}-{task-name}/` (e.g., `tasks/196-team-page/`)
2. **Extract Issue Number**: Parse the issue number from the directory name
3. **Create Status Summary**: After spec-checker validation is complete, create a 2-paragraph summary of what the specification covers (NOT a summary of the process that created it)
4. **Push to GitHub**: Use `push-file.sh` to sync with status summary:
```bash
~/.claude/plugins/marketplaces/edspencer-agents/plugins/product-team/skills/github-task-sync/push-file.sh {issue-number} SPEC {status-file} SPEC.md
```
**Status Summary Format:**
The status summary should be a 2-paragraph overview describing WHAT the spec covers:
```markdown
**Status:** Complete
This specification outlines requirements for [high-level feature description]. [Explain the scope and what problem it solves].
Key requirements include: [list 3-5 most important requirements]. [Mention any important constraints, integrations, or technical considerations].
- Key requirement 1 (optional bullet points)
- Key requirement 2
- Key requirement 3
```
**Example:**
```bash
# After creating 2-paragraph status summary in a temp file or variable
~/.claude/plugins/marketplaces/edspencer-agents/plugins/product-team/skills/github-task-sync/push-file.sh 196 SPEC spec-status.txt ./tasks/196-team-page/SPEC.md
```
This creates/updates the SPEC comment on GitHub with:
- Heading: "Specification:"
- Status summary visible at top
- Full spec content in collapsible `<details>` section
**Reference:** See `~/.claude/plugins/marketplaces/edspencer-agents/plugins/product-team/skills/github-task-sync/SKILL.md` for complete documentation.

91
commands/agentic-implement-plan.md Normal file
View File

@@ -0,0 +1,91 @@
---
allowed-tools: Bash, Edit, Grep, Read, WebSearch, WebFetch, Write
argument-hint: [plan-file] [instructions]
description: Fully implement a plan using sub agents
---
## Task: Use sub agents to implement an entire plan from start to finish
You will make extensive use of the following sub-agents:
@code-writer - Use this agent to implement each phase of the plan
@browser-tester - Use this agent to test the web app using Playwright after each phase of the plan (if there were UI changes)
The sub-agents have specialized knowledge and abilities, but also, delegating to them allows you to use less of your LLM context on solving issues, as you are playing an orchestrator role. Try to delegate to these sub-agents as much as possible.
## Process
Read the entire PLAN.md file you are given.
Starting with Phase 1, delegate the implementation of the phase to the code writer agent. The code writer agent will have minimal context so you will have to give it the information it needs, which should include a reference to the PLAN.md file, which phase the agent should work on, any relevant context about the implementation so far, and so on. The code writer agent does have general context about this application, and understands how to look up technical docs.
After the code writer agent finishes a batch of work and you check it: if it got something wrong that you can easily fix, fix it. If it got something wrong that needs extensive correction, stop and ask me for help
### Process for each phase
The process for each phase is as follows (in order):
1. Ask the code writer agent to implement the phase
2. Check the code writer agent's implementation
3. If it got something wrong that you can easily fix, fix it, else escalate to me
4. Run the `lint`, `format`, `test`, and `build` commands at the project root to catch any issues early
5. If the phase contains UI changes, ask the web app tester agent to test the web app using Playwright after the phase
6. Check that the PLAN.md and LOG.md have been updated to reflect the completed work
If all of those checks pass, then the phase is complete and you can move on to the next phase. If any of those checks fail, you should stop and ask me for help.
## Example run
A typical full agentic implementation might look like this, for a PLAN.md containing 4 stages, where stages 2 and 3 contain UI changes that should be checked:
1. You read the PLAN.md file
2. You asked the code writer agent to implement phase 1
3. You check what the code writer agent did in its phase 1 implementation and decided it was correct
4. You asked the code writer agent to implement phase 2 (which contains UI changes)
5. You check what the code writer agent did in its phase 2 implementation and decided it was correct
6. You asked the web app tester agent to test the web app using Playwright after phase 2, because it contains UI changes
7. You asked the code writer agent to implement phase 3 (which contains UI changes)
8. You check what the code writer agent did in its phase 3 implementation and decided it was correct
9. You asked the web app tester agent to test the web app using Playwright after phase 3, because it contains UI changes
10. You asked the code writer agent to implement phase 4
11. You check what the code writer agent did in its phase 4 implementation and decided it was correct
At this point, you should prepare your final report:
## Creating the Final Commit Message
Before reporting back to the user, create a commit message for the completed work:
1. **Check for COMMIT_MESSAGE.md**: Look for a COMMIT_MESSAGE.md file in the task directory
2. **If COMMIT_MESSAGE.md exists:**
- Read the draft commit message that was created during planning
- Verify it still accurately reflects what was actually implemented across all phases
- If the implementation deviated significantly from the original plan (e.g., additional features added, approaches changed, scope adjusted):
- Update COMMIT_MESSAGE.md to reflect the actual implementation
- Ensure it mentions any major deviations or additions
- Use the (possibly updated) COMMIT_MESSAGE.md as the basis for your suggested commit message
3. **If COMMIT_MESSAGE.md does not exist:**
- Create a commit message from scratch based on the actual changes made across all phases
- Follow the commit message guidelines below
### Commit Message Guidelines
The commit message should:
- Start with a 1-sentence summary on its own line
- Briefly explain what was done and why
- Typically be 2-4 paragraphs long (shorter for small changes, ~1-2 paragraphs for <300 LOC)
- Call out any key architectural or API changes
- Call out any key dependencies or tools being added/removed
- Call out any key data model changes
- Call out any key environment variable changes
- Avoid value judgments (e.g., don't say "improves" or "better")
- Keep it factual and not boastful
## Final Report
Give a full report back to the user, including:
- Summary of all phases completed
- Any issues encountered and how they were resolved
- The suggested git commit message (based on COMMIT_MESSAGE.md if it existed)

29
commands/agentic-spec-and-plan.md Normal file
View File

@@ -0,0 +1,29 @@
---
allowed-tools: Bash, Edit, Grep, Read, WebSearch, WebFetch, Write
argument-hint: [instructions]
description: Write a spec and plan using sub agents
---
## Task: Use sub agents to create an entire plan from start to finish
This SlashCommand is just a wrapper around the /agentic-create-spec and /agentic-create-plan SlashCommands. It should just call those SlashCommands in order.
## Process
1. Call the /agentic-create-spec SlashCommand
2. Call the /agentic-create-plan SlashCommand
3. Report back with the status of the plan
## Instructions
- If, during investigation and creation of the plan, it becomes clear that the specification was not possible, immediately stop what you're doing and ask the user for how to proceed.
- You may be given a reference to a github issue or other ticket; if so, attempt to read the issue/ticket yourself first to make sure you have a clear understanding of the task at hand. Use that information to aid in your prompting of the sub agents via the slash commands.
## GitHub Sync
**Note:** If working with a GitHub issue, the `/agentic-create-spec` and `/agentic-create-plan` SlashCommands will automatically sync task files to GitHub:
- After spec creation: SPEC.md will be pushed to GitHub issue
- After plan creation: PLAN.md, TEST_PLAN.md, and COMMIT_MESSAGE.md will be pushed to GitHub issue
This ensures the GitHub issue stays synchronized throughout the specification and planning process.

17
commands/check-code.md Normal file
View File

@@ -0,0 +1,17 @@
---
allowed-tools: Bash, Edit, Grep, Read, WebSearch, WebFetch, Write
argument-hint: [plan-file] [instructions]
description: Check code implementation against plan and rules
---
# Check code implementation against plan and rules
Your task is to check the code implementation of a plan ($1) against the plan requirements and code-rules.md. If you were given additional instructions ($2), please pay attention to them. Output a REVIEW.md of your findings and recommendations, and then offer to implement any of them that you think are most pressing (if any).
## Instructions
- Read the plan document carefully before starting to review the implementation
- Look at the staged git changes to see what has been implemented (if nothing is staged, look at unstaged instead)
- Check each part of the plan to see if it has been implemented fully and correctly
- Do not build the apps/web app - the developer already has a dev build running on port 3000 and running build interferes with this
- If you find any areas where the plan does not appear to have been implemented fully or correctly, please note them in the REVIEW.md

60
commands/check-plan.md Normal file
View File

@@ -0,0 +1,60 @@
---
allowed-tools: Bash, Edit, Grep, Read, WebSearch, WebFetch, Write
argument-hint: [plan-file] [spec-file]
description: Check a plan document against rules and suggest improvements
---
# Check a plan document against rules and suggest improvements
You have been given a plan document to check ($1). Your task is to fully read and understand the plan document, validate it against plan-rules.md, and suggest improvements if needed.
You may be given a spec document ($2) that the plan was based on, and you should compare the plan document against this spec document to ensure it is up to date and accurate.
## Output
You should provide two outputs:
### Output 1: Content Summary (For GitHub Comments)
Create a file called `PLAN-STATUS.md` containing a 2-paragraph content overview that someone can read to understand what the implementation plan covers. This should answer: "What will be done if we follow this plan? What are the important phases, approach, and scope?"
Format:
- **First paragraph:** High-level overview of the implementation approach (phases, methodology, overall strategy)
- **Second paragraph:** Key phases/components, timeline structure, and major deliverables
- **Optional bullet points:** 3-5 bullet points highlighting the most important implementation phases or deliverables
Example:
```
The implementation plan uses a phased approach to build the user account deletion feature over 6 weeks. It begins with infrastructure setup and verification workflows, progresses through database cleanup and notification systems, and concludes with testing and documentation.
Key phases include: (1) Creating the deletion request and verification system, (2) Implementing database cleanup with transaction safety, (3) Building notification to third parties, (4) Performance optimization and gradual deletion, and (5) Comprehensive testing and documentation. Each phase builds on previous work with clear dependencies and success criteria.
- Phased implementation over 6 weeks with clear dependencies
- Transaction-safe database cleanup with gradual removal
- Comprehensive testing (unit, integration, performance)
- Full audit logging and compliance documentation
- Backwards compatibility maintained throughout
```
### Output 2: Validation Feedback Report
Return a comprehensive list of issues found and suggested improvements. Propose a set of edits to the file, but do not actually make them without user approval.
## Instructions
- Read the plan document carefully before starting to check it
- Compare the plan document against the spec document if provided, extract any ways in which the plan deviates from the spec
- Compare the plan document against ./.claude/docs/processes/plan-rules.md, extract any ways in which the plan deviates from the plan requirements
- Check to see if the plan calls for the creation of any functions or features that don't seem to be used or called for and highlight them
## Syncing Status to GitHub
After generating PLAN-STATUS.md and your validation feedback, sync the status to the GitHub issue:
1. **Determine issue number**: Extract from task directory name (format: `tasks/{issue-number}-{task-name}/`)
2. **Push status to GitHub**: Use the `github-task-sync/push-file.sh` script to update the PLAN comment with status summary
```bash
~/.claude/plugins/marketplaces/edspencer-agents/plugins/product-team/skills/github-task-sync/push-file.sh <issue-number> PLAN PLAN-STATUS.md PLAN.md
```
This keeps the GitHub issue updated with the current plan validation status. The PLAN-STATUS.md file provides the 2-paragraph summary that appears at the top of the collapsible PLAN comment on GitHub.

100
commands/check-spec.md Normal file
View File

@@ -0,0 +1,100 @@
---
allowed-tools: Bash, Grep, Read
argument-hint: [spec-file]
description: Validate a specification document against spec-rules.md
---
# Check a specification document against rules
Your task is to validate a SPEC.md file ($1) against the requirements in spec-rules.md and provide structured feedback.
## Your Task
Read the specification document and validate it against Check `.claude/docs/processes/spec-rules.md` (project) OR `~/.claude/plugins/marketplaces/edspencer-agents/plugins/product-team/docs/processes/spec-rules.md` (plugin). This is a read-only validation task - do not modify the spec file.
### Validation Checklist
Check the following aspects:
**File Location and Naming:**
- [ ] File is in `./tasks/[task-name]/SPEC.md` format
- [ ] Task name is clear and descriptive
**Required Structure:**
- [ ] Has clear Task heading stating what needs to be done
- [ ] Includes Background section explaining context and problem
- [ ] Includes Current State section describing what exists
- [ ] Includes Requirements section with detailed, numbered list
- [ ] Includes Success Criteria section with testable criteria
**Content Quality:**
- [ ] Description is clear and comprehensive
- [ ] Has enough detail for plan-writer to create implementation plan
- [ ] Avoids large code snippets (except to illustrate patterns)
- [ ] New dependencies are clearly called out
- [ ] Includes relevant links to code, docs, or resources
- [ ] Uses proper markdown formatting
**Completeness:**
- [ ] All necessary context is provided
- [ ] Requirements are specific and actionable
- [ ] Success criteria are testable and clear
- [ ] No implementation details mixed with requirements
## Output Format
Provide a structured feedback report with two parts:
### Part 1: Content Summary (For GitHub Comments)
Create a file called `SPEC-STATUS.md` containing a 2-paragraph content overview that someone can read to understand what the specification covers. This should answer: "What requirements does this specification define? What is the scope and key goals?"
Format:
- **First paragraph:** High-level overview of what the spec calls for
- **Second paragraph:** Key requirements, scope, and important constraints
- **Optional bullet points:** 3-5 bullet points highlighting the most important requirements
Example:
```
This specification outlines requirements for implementing user account deletion functionality. The feature must allow users to permanently delete their accounts and associated data while maintaining system integrity and compliance with data protection regulations.
Key requirements include: database cleanup of all user records, notification of deletion to third-party services, verification steps to prevent accidental deletion, and audit logging of all deletions. The implementation must support gradual data removal to avoid performance impact on the production system.
- Permanent and irreversible account deletion with full data cleanup
- Compliance with GDPR and data protection requirements
- Deletion verification workflow to prevent accidents
- Audit trail for compliance and security
```
### Part 2: Validation Feedback Report
### Validation Summary
- Overall assessment (Pass / Pass with suggestions / Needs revision)
- Number of critical issues
- Number of suggestions
### Critical Issues
List any missing required sections or major problems that must be fixed.
### Suggestions
List improvements that would enhance the spec quality.
### Positive Observations
Note what the spec does well.
## Syncing Status to GitHub
After generating SPEC-STATUS.md and your validation feedback, sync the status to the GitHub issue:
1. **Determine issue number**: Extract from task directory name (format: `tasks/{issue-number}-{task-name}/`)
2. **Push status to GitHub**: Use the `github-task-sync/push-file.sh` script to update the SPEC comment with status summary
```bash
~/.claude/plugins/marketplaces/edspencer-agents/plugins/product-team/skills/github-task-sync/push-file.sh <issue-number> SPEC SPEC-STATUS.md SPEC.md
```
This keeps the GitHub issue updated with the current spec validation status. The SPEC-STATUS.md file provides the 2-paragraph summary that appears at the top of the collapsible SPEC comment on GitHub.
## Next Steps
If there are critical issues, recommend revisions before proceeding to plan creation.
If the spec passes validation, confirm it's ready for the plan-writer agent.

34
commands/create-issue.md Normal file
View File

@@ -0,0 +1,34 @@
---
allowed-tools: Bash, Edit, Grep, Read, WebSearch, WebFetch, Write
argument-hint: [instructions]
description: Create an issue based on instructions, optionally creating a spec and plan
---
# Create an issue based on instructions
You're going to be given a variety of different possible instructions, but typically you're going to need to use the Github Task Sync skill to create an issue in the Github issues for this repository and potentially create a spec and a plan using the /agentic-create-spec and /agentic-create-plan commands. If the instructions don't specifically say don't do either one or both of those, then the default is that you should do so.
You are playing the role of orchestrator of these sub-agents, so it's important that you understand the issue yourself. However, you're going to delegate most of the work to the sub-agents to create spec and the plan. Then, you're going to report back afterwards as to what happened.
## Label Determination
Before creating the issue, analyze the title and description to determine appropriate GitHub labels:
**Available labels:**
- `UI` - User interface related (buttons, styling, layout, components, forms, mobile responsiveness, themes)
- `CLI` - Command-line interface related (commands, terminal, Git operations, flags, arguments)
- `bug` - Bug fixes and issue resolutions (fix, broken, crash, error, regression)
- `feature` - New features and enhancements (add, implement, support, new capability)
**Decision process:**
1. Scan the title and description for keyword patterns
2. Apply multiple labels if the issue touches multiple areas (e.g., `UI,bug` for styling bug)
3. Pass comma-separated labels to the `create-issue.sh` script via the 4th parameter
4. Never apply both `bug` and `feature` to the same issue
5. Tags are optional - only apply if context clearly matches
**Example label decisions:**
- "Fix login button styling on mobile" → `UI,bug` (UI styling + bug fix)
- "Add new extract command for filtering by date" → `CLI,feature` (CLI command + new feature)
- "Resolve authentication redirect loop" → `bug` (bug fix only)
- "Implement dark mode toggle in settings" → `UI,feature` (UI component + new feature)

78
commands/finish.md Normal file
View File

@@ -0,0 +1,78 @@
---
allowed-tools: Bash, Edit, Grep, Read, WebSearch, WebFetch, Write
argument-hint: [plan-file] [instructions]
description: Finish a planned piece of work
---
# Finish a planned piece of work
You have been given a plan document that has been implemented ($1). Your task is to run final cleanup commands and propose a git commit message
## Instructions
You should be able to do some or all of these in parallel:
- Run `pnpm run build` at the project root, so we can catch any build failures early
- Run `pnpm run test` at the project root, so we can catch any test failures early
- Run `pnpm run format` at the project root, so we can catch any formatting issues early
- Run `pnpm run lint` at the project root, so we can catch any lint issues early. Fix any lint issues that affect files you have edited
Give your final thoughts on the implementation. If you find any issues, please note them now but do not attempt to fix them.
If everything looks like it was completely successful, archive this task by moving it from ./tasks/TASK-NAME to ./tasks/archive/TASK-NAME (use git mv for this)
## Creating the Final Commit Message
Follow these steps to create the final commit message:
1. **Check for COMMIT_MESSAGE.md**: Look for a COMMIT_MESSAGE.md file in the task directory
2. **If COMMIT_MESSAGE.md exists:**
- Read the draft commit message that was created during planning
- Verify it still accurately reflects what was actually implemented
- **Verify GitHub closing syntax** (if applicable): If the task directory follows `tasks/{issue-number}-{task-name}/` pattern:
- Check that the commit message includes the GitHub issue closing syntax at the end
- For bug fixes: Should end with `Fixes #{issue-number}`
- For features/other tasks: Should end with `Closes #{issue-number}`
- If missing, add the appropriate closing line before finalizing
- If the implementation deviated significantly from the original plan (e.g., additional features added, approaches changed, scope adjusted):
- Update COMMIT_MESSAGE.md to reflect the actual implementation
- Ensure it mentions any major deviations or additions
- Verify the GitHub closing syntax is still appropriate and present
- Use the (possibly updated) COMMIT_MESSAGE.md as the basis for your final commit message
3. **If COMMIT_MESSAGE.md does not exist:**
- Create a commit message from scratch based on the actual changes made
- If the task directory follows `tasks/{issue-number}-{task-name}/` pattern, include the appropriate GitHub closing syntax (Fixes or Closes followed by the issue number)
- Follow the commit message guidelines below
### Commit Message Guidelines
Your git commit message should:
- Start with a 1-sentence summary on its own line
- Be a sentence or two if only a file or two were changed, many paragraphs if dozens of files were changed, and anything in between
- Keep it factual and not boastful
- Briefly explain what we're doing and why
- Not just summarize the changes
- Typically be 2-4 paragraphs long (shorter for small changes, ~1-2 paragraphs for <300 LOC)
- Call out any key architectural or API changes
- Call out any key dependencies or tools being added/removed
- Call out any key data model changes
- Call out any key environment variable changes
- Avoid value judgments (e.g., don't say "improves" or "better")
## Syncing Task Files to GitHub
Before archiving the task, sync all task files to the GitHub issue as the final step:
1. **Determine the issue number**: Extract it from the task directory name (format: `tasks/{issue-number}-{task-name}/`)
2. **Sync all files**: Run the push.sh skill to upload SPEC.md, PLAN.md, TEST_PLAN.md, and COMMIT_MESSAGE.md to the issue
```bash
~/.claude/plugins/marketplaces/edspencer-agents/plugins/product-team/skills/github-task-sync/push.sh <issue-number> <task-directory>
```
3. **Verify**: Confirm all files appear on the GitHub issue as collapsible comments
4. **Archive task**: After syncing, move the task directory to ./tasks/archive/ using `git mv`
This ensures all documentation is centralized on the GitHub issue before the task is archived.
---
Don't stage anything or commit anything, just propose the final git commit message now:

200
commands/run-integration-tests.md Normal file
View File

@@ -0,0 +1,200 @@
---
allowed-tools: Bash, Edit, Grep, Read, WebSearch, WebFetch, Write(test/REPORT.md)
argument-hint: [optional-instructions]
description: Run Integration tests from the test plan via Playwright hitting the live UI
---
# Run Integration Tests
If not given specific instructions otherwise, run all tests listed in `./test/integration/TEST-PLAN.md` systematically, using their Comprehensive Tests section. If given a more specific set of instructions, follow them instead.
Execute the test plan using Playwright automation. Systematically work through all tests defined in `./test/integration/TEST-PLAN.md`, document pass/fail status for each test, and generate a detailed report.
## Execution Process
### 1. Session Initialization
ALWAYS begin by:
1. Navigate to http://ngrok.edspencer.net/demo
2. Click the button to create a demo account
3. Wait for successful authentication before proceeding
ALWAYS finish by:
1. Logging out of the application (just navigate to /logout) - this will clear the database of cruft demo data
### 2. Test Execution
Work through ALL test sections in `./test/integration/TEST-PLAN.md` systematically. For each test:
- Execute the test steps using Playwright MCP tools
- Record PASS or FAIL status
- Note any console errors or warnings
- Do NOT attempt to debug failures - just document them
### 3. Testing Guidelines
**DO:**
- Navigate by clicking links and UI elements (not direct URLs except /demo)
- Check browser console regularly
- Test systematically through all items
- Record exact error messages when failures occur
- Note visual issues or unexpected behavior
**DO NOT:**
- Skip tests or categories
- Attempt to debug or fix issues found
- Make code changes
- Stop testing when failures are found - continue through all tests
- Navigate to URLs directly (except initial /demo)
### 4. Playwright MCP Usage
Use Playwright MCP tools extensively:
- `browser_navigate` - Navigate to pages
- `browser_snapshot` - Capture accessibility snapshots (preferred for testing)
- `browser_take_screenshot` - Take visual screenshots
- `browser_click` - Click elements
- `browser_type` - Fill forms
- `browser_console_messages` - Check for errors
- `browser_wait_for` - Wait for elements or text
### 5. Report Generation
After testing is complete, generate a comprehensive report at `./test/integration/runs/YYYY-MM-DD-N/REPORT.md` (where N is an index for multiple runs on the same day).
The report should have the following structure:
```markdown
# UI Test Execution Report
**Date**: [Current date]
**Tested By**: Claude Code (UI Test Runner)
**Environment**: http://ngrok.edspencer.net
**Browser**: Playwright Chromium
---
## Executive Summary
- **Total Tests**: [number]
- **Passed**: [number] ([percentage]%)
- **Failed**: [number] ([percentage]%)
- **Skipped**: [number] (if any)
- **Overall Status**: PASS | FAIL | PARTIAL
**Critical Issues Found**: [number]
**Major Issues Found**: [number]
**Minor Issues Found**: [number]
---
## Test Results by Category
### 1. Navigation - Sidebar
**Status**: PASS | FAIL | PARTIAL
**Tests Passed**: X/Y
#### 1.1 Sidebar Structure
- [x] Test name - PASS
- [ ] Test name - FAIL: [brief reason]
- [x] Test name - PASS
[Continue for each test...]
---
### 2. Navigation - Careers Section
[Same format as above]
---
### 3. Coming Soon Pages
[Same format as above]
---
[Continue for all categories...]
---
## Issues Found
### Critical Issues
[None found] OR:
1. **Issue**: [Brief description]
- **Location**: [Where it occurs]
- **Steps to Reproduce**: [Exact steps]
- **Expected**: [What should happen]
- **Actual**: [What actually happens]
- **Evidence**: [Screenshot references, console errors]
### Major Issues
[Format same as critical]
### Minor Issues
[Format same as critical]
---
## Console Errors
[List all console errors found during testing with page context]
---
## Test Coverage
**Categories Completed**: X/7
**Individual Tests Completed**: X/Y
**Not Tested** (if any):
- [List any tests that couldn't be executed with reasons]
---
## Recommendations
[High-level recommendations for addressing failures, but no specific debugging or code changes]
---
## Conclusion
[Summary paragraph of overall test execution]
```
## Important Constraints
- **DO NOT debug issues** - only document them
- **DO NOT examine code** unless needed to understand what to test
- **DO NOT propose fixes** - only report findings
- **DO continue testing** even after failures
- **DO be thorough** - test every checkbox in the test plan
- **DO capture evidence** - error messages and console logs
- **ALWAYS create demo account** at start of session
- **SAVE report to ./test/integration/runs/YYYY-MM-DD-N/REPORT.md** when complete
## Success Criteria
A successful test run means:
1. All tests in TEST-PLAN.md were attempted
2. Clear PASS/FAIL status recorded for each test
3. Console errors documented
4. Comprehensive report generated at `./test/integration/runs/YYYY-MM-DD-N/REPORT.md`
The tests themselves may pass or fail - your job is to execute them all and report accurately, not to achieve 100% pass rate.

20
commands/write-code.md Normal file
View File

@@ -0,0 +1,20 @@
---
allowed-tools: Bash, Edit, Grep, Read, WebSearch, WebFetch, Write
argument-hint: [plan-file] [instructions]
description: Write code to implement part of a plan
---
# Write code to implement a plan document
You have been given a plan document to implement ($1). Your task is to fully read and understand the plan document, and then write the code to implement it. If you were given additional instructions ($2), please pay attention to them.
## Instructions
- Read the plan document carefully before starting to implement it
- Update the plan document as you go; each time you complete a task, mark it as done in the plan document using the checkbox
- Keep a LOG.md file in the same directory as the plan document, and update it as you go. This should be a log of all key decisions you make, and any issues you encounter and how you resolved them, deviations from the plan, updated guidance from the user, and so on.
- Do run a `pnpm run build` for the `apps/web` project when you think you are done with a phase or entire implementation, so we can catch any build failures early
- Do run `pnpm run test` at the project root when you think you are done with a phase or entire implementation, so we can catch any test failures early
- Do run `pnpm run format` at the project root when you think you are done with a phase or entire implementation, so we can catch any formatting issues early
- Do run `pnpm run lint` at the project root when you think you are done with a phase or entire implementation, so we can catch any lint issues early. Fix any lint issues that affect files you have edited
- The dev server is almost always running whenever you are working. The server runs on port 3000, and its logs are continually written to ./apps/web/.next-dev.log in the root of the project. Scan this file for errors and warnings, and use it to debug issues.

128
commands/write-plan.md Normal file
View File

@@ -0,0 +1,128 @@
---
allowed-tools: Bash, Edit, Grep, Read, WebSearch, WebFetch, Write(PLAN.md)
argument-hint: [spec-file]
description: Create a plan to implement a certain specification
---
# Create a plan for implementing a certain specification
Your task is to create a PLAN.md file that outlines the steps required to implement a certain specification.
## Data you have access to
### Spec file (argument 1)
The spec file argument ($1) to understand what we're importing this time. It will provide you will some or all of the following sections of information:
- Task - overall short description of the task
- Background Reading - any additional information you should read to understand the context of the task
- Specific Requirements - any specific requirements for the task
It may contain other information too, which you should pay attention to.
## Your Task
Your task is to use the details in the spec file, read and understand any content it refers to, and ultrathink to create a detailed PLAN.md document in the same directory as the spec file ($1). The PLAN.md document should contain a thorough plan for implementing the specification, following any additional instructions outlined in the spec file.
### Plan requirements
IMPORTANT: Our PLAN.md documents follow very strict plan requirements, as detailed in .claude/docs/processes/plan-rules.md. Read that file very carefully and adhere strictly to its guidance.
**CRITICAL REQUIREMENTS FROM plan-rules.md:**
1. **Documentation Manager Consultation**: After drafting the initial plan but BEFORE using `/check-plan`, you MUST consult the documentation-manager agent to identify which documentation files in `.claude/docs/tech/` and `.claude/docs/user/` need updates. Include their specific guidance in your plan's Documentation section.
2. **GitHub Task Sync**: Include tasks to sync task files to GitHub at appropriate points using the `github-task-sync` skill. Plans should pull latest files from GitHub before starting work and push updates after major phases. See plan-rules.md section "GitHub Task Sync Integration" for complete workflow details.
3. **After-Action Report Phase**: Every plan MUST include a final phase for submitting an after-action report to the process-manager agent. See plan-rules.md for the exact structure required.
### GitHub Task Sync Workflow
Before beginning work, check if a GitHub issue exists for this task:
- If the task directory is named `{issue-number}-{task-name}/`, pull latest files from GitHub using `pull.sh`
- Include sync tasks in the plan for pushing updates after completing major phases
- The `/finish` SlashCommand will handle final sync to GitHub before archiving
After creating the plan files, sync them to GitHub:
1. **Create Status Summary**: Write a 2-paragraph summary describing WHAT the plan will implement (NOT the process):
- **Status:** Draft
- First paragraph: High-level overview of implementation approach and phases
- Second paragraph: Key phases/components and major deliverables
- Optional: 3-5 bullet points highlighting most important phases
2. **Push to GitHub**: Extract the issue number from the directory name and sync:
```bash
~/.claude/plugins/marketplaces/edspencer-agents/plugins/product-team/skills/github-task-sync/push-file.sh {issue-number} PLAN {status-file} PLAN.md
~/.claude/plugins/marketplaces/edspencer-agents/plugins/product-team/skills/github-task-sync/push.sh {issue-number} {task-directory}
```
This creates/updates the PLAN comment with status summary visible and full plan in collapsible section, plus syncs TEST_PLAN.md and COMMIT_MESSAGE.md.
### Separate Test Plan Requirements
Most plans you will be asked to make will involve some level of testing. You should create a separate TEST_PLAN.md file in the same directory as the spec file ($1). The TEST_PLAN.md file should contain a thorough plan for testing the specification, following any additional instructions outlined in the spec file.
If the plan genuinely does not call for any testing, do not create a TEST_PLAN.md file.
If you do create a TEST_PLAN.md file, refer to its existence in the main PLAN.md file, which should also contain a very high level summary of what the test plan calls for.
### Commit Message
You should create a commit message for the changeset you propose in the PLAN.md. You should save this in a file called COMMIT_MESSAGE.md in the same directory as the spec file ($1). The commit message should correspond in detail to the changeset you propose in the PLAN.md, but at most should run to about 5-6 paragraphs. It should usually be 2-3 paragraphs unless the changeset are enormous.
Commit message instructions:
- should start with a 1-sentence summary on its own line
- should briefly explain what we're doing any why
- should not just summarize the changeset
- should typically be 2-4 paragraphs long
- should be shorter than this if only a small amount of code is being changed (e.g. if less than ~300LOC changed, a paragraph or two should suffice)
- should call out any key architectural or API changes
- should call out any key dependencies or tools being added/removed
- should call out any key data model changes
- should call out any key environment variable changes
- do not attempt to assess the value of the changes, e.g. don't say things like "This change improves the information architecture by separating document management from the primary navigation flow while keeping career-focused features prominently displayed and easily accessible."
#### GitHub Issue Closing Syntax
If the task directory follows the pattern `tasks/{issue-number}-{task-name}/`, the commit message MUST include GitHub's issue closing syntax at the end:
- Extract the issue number from the directory name
- For bug fixes (check SPEC.md labels): Use `Fixes #{issue-number}`
- For features and other tasks: Use `Closes #{issue-number}`
- Add this as a separate line at the end of the commit message body
GitHub will automatically close the associated issue when the commit is merged.
**Example with closing syntax:**
```
fix: invalidate top projects cache when creating projects
When users create a project via the dashboard, the TopProjects component and NavProjects sidebar don't refresh to show the new project until they manually refresh the page. This occurs because useCreateProject() only invalidates the `/api/projects` SWR cache key, while TopProjects and NavProjects use the `/api/projects/top?limit=5` cache key.
This fix adds useTopProjects() to useCreateProject() and calls mutate() on both cache keys after successful creation, ensuring all components receive updated data immediately.
Closes #213
```
#### Example commit messages (without closing syntax for context)
In this paragraph:
```
This change restructures the main sidebar navigation by removing the Documents section and introducing a new "Careers" section that consolidates career-related features. The Careers section groups together existing features (Standup and "Reports") with two new coming-soon pages (Performance Review and Workstreams), creating a more intuitive organization for users focused on career advancement and documentation.
```
All was fine until the ", creating a more intuitive ..." stuff - just don't include value judgments like that, leave them out.
Similarly, here, the final sentence is completely unnecessary and should not be present in a commit message:
```
The Documents section has been completely removed from the navigation sidebar, though the `/documents` page and its associated functionality remain accessible via direct URL. This change improves the information architecture by separating document management from the primary navigation flow while keeping career-focused features prominently displayed and easily accessible.
```
That was fine until the "direct URL.", which is where it should have ended.
# Get started
Please start your plan and save it to PLAN.md

107
commands/write-spec.md Normal file
View File

@@ -0,0 +1,107 @@
---
allowed-tools: Bash, Edit, Grep, Read, WebSearch, WebFetch, Write(SPEC.md)
argument-hint: [topic]
description: Create a specification document for a task
---
# Create a specification document for a task
Your task is to create a SPEC.md file from the topic or requirements provided by the user.
## Data you have access to
### Topic (argument 1)
The topic argument ($1) provides the initial description of what needs to be specified. This may be:
- A brief task description
- User requirements or goals
- A problem statement that needs solving
## Your Task
Your task is to gather all necessary information (through questions if needed) and create a comprehensive SPEC.md document in `./tasks/[task-name]/SPEC.md` following the spec-rules.md guidelines.
### Spec Requirements
IMPORTANT: All SPEC.md documents must follow the strict requirements in Check `.claude/docs/processes/spec-rules.md` (project) OR `~/.claude/plugins/marketplaces/edspencer-agents/plugins/product-team/docs/processes/spec-rules.md` (plugin). Read that file very carefully and adhere to its guidance.
**Key Requirements:**
1. **File Location**: Always create in `./tasks/[task-name]/SPEC.md` where [task-name] is derived from the task
2. **Required Structure**:
- Task heading with clear statement
- Background section explaining context and problem
- Current State section describing what exists today
- Requirements section with detailed, numbered list
- Success Criteria section with testable criteria
3. **Content Guidelines**:
- Clear, comprehensive description with all relevant context
- No large code snippets (except to illustrate patterns)
- Enough detail for plan-writer to create implementation plan
- Call out new dependencies clearly
- Include links to relevant code, docs, or resources
### Gathering Requirements
If the initial topic ($1) lacks sufficient detail:
- Ask clarifying questions about the problem and goals
- Understand what currently exists
- Identify what needs to change or be added
- Determine success criteria
- Identify any constraints or dependencies
### Task Naming
Choose a clear, descriptive task name for the directory:
- Use lowercase with hyphens: `add-user-auth`, `fix-login-bug`, `refactor-api`
- Keep it concise but meaningful
- Ensure it matches the task heading
### GitHub Issue Creation
If the user explicitly requests that a GitHub issue be created, or if this is a significant feature requiring tracking:
1. **Ask the user** if a GitHub issue should be created for this task
2. **If yes**, use the github-task-sync skill's `create-issue.sh` script to create the issue and initialize the task directory:
```bash
~/.claude/plugins/marketplaces/edspencer-agents/plugins/product-team/skills/github-task-sync/create-issue.sh "<task-title>" "<brief-description>"
```
3. **Directory naming**: The script automatically creates a directory named `{issue-number}-{task-slug}/`
4. **Work locally**: Create SPEC.md in the task directory as usual
5. **Sync to GitHub**: After creating SPEC.md, sync it with a status summary (see below)
**Note:** GitHub issues serve as the source of truth for task documentation. Local task files are a working cache that agents can edit easily.
### GitHub Sync After Spec Creation
After creating SPEC.md, if the task directory follows the pattern `tasks/{issue-number}-{task-name}/`:
1. **Create Status Summary**: Write a 2-paragraph summary describing WHAT the specification covers (NOT the process):
- **Status:** Draft
- First paragraph: High-level overview of what the spec calls for
- Second paragraph: Key requirements, scope, and important constraints
- Optional: 3-5 bullet points highlighting most important requirements
2. **Push to GitHub**: Extract the issue number from the directory name and sync:
```bash
~/.claude/plugins/marketplaces/edspencer-agents/plugins/product-team/skills/github-task-sync/push-file.sh {issue-number} SPEC {status-file} SPEC.md
```
**Status Summary Format Example:**
```
**Status:** Draft
This specification outlines requirements for implementing user account deletion functionality. The feature must allow users to permanently delete their accounts and associated data while maintaining system integrity and compliance with data protection regulations.
Key requirements include: database cleanup of all user records, notification of deletion to third-party services, verification steps to prevent accidental deletion, and audit logging of all deletions. The implementation must support gradual data removal to avoid performance impact on the production system.
- Permanent and irreversible account deletion with full data cleanup
- Compliance with GDPR and data protection requirements
- Deletion verification workflow to prevent accidents
- Audit trail for compliance and security
```
This creates/updates the SPEC comment on GitHub with the status summary visible and full spec in a collapsible section.
# Get started
Please gather requirements and create the SPEC.md file.