add GitHub-integrated feature workflow commands and bump version to 1.1.25
This commit introduces a comprehensive feature management workflow that integrates with GitHub Issues and Projects for better task tracking and team collaboration. ## New Commands Added - `/publish-to-github`: Publishes features from /specs to GitHub by: - Creating an Epic issue with full requirements - Creating individual task issues for each implementation step - Setting up a GitHub Project board linked to the repository - Creating labels for organization (epic, feature/*, phase-*) - Generating a github.md reference file in the specs folder - `/continue-feature`: Implements the next available task by: - Querying open issues for the feature - Checking task dependencies to find unblocked work - Updating GitHub Project board status (In Progress -> Done) - Adding implementation details as issue comments - Providing fallback to implementation-plan.md when offline ## Updated Commands - `/create-feature`: Enhanced with clearer structure including: - Detailed implementation plan format template - Requirements for atomic, agent-implementable tasks - Guidance on next steps after feature creation - Better documentation for the /specs folder structure ## Package Updates - Bumped version from 1.1.24 to 1.1.25 All changes are mirrored in both the root .claude/commands/ folder and the create-agentic-app/template/.claude/commands/ folder to ensure new projects created with the CLI have access to these workflows. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Leon van Zyl
355
.claude/commands/continue-feature.md
Normal file
355
.claude/commands/continue-feature.md
Normal file
@@ -0,0 +1,355 @@
|
||||
---
|
||||
description: Continue implementing the next task for a GitHub-published feature
|
||||
---
|
||||
|
||||
# Continue Feature Implementation
|
||||
|
||||
This command finds and implements the next available task for a feature that has been published to GitHub.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- The GitHub CLI (`gh`) must be authenticated
|
||||
- The feature must have been published to GitHub (github.md exists in the feature folder)
|
||||
- The feature folder should be attached to the conversation
|
||||
|
||||
## Instructions
|
||||
|
||||
### 1. Locate the Feature
|
||||
|
||||
Look for the feature folder attached to the conversation. It should be at `/specs/{feature-name}/` and contain:
|
||||
|
||||
- `requirements.md` - Feature requirements (for context)
|
||||
- `implementation-plan.md` - Original task breakdown
|
||||
- `github.md` - GitHub references (required)
|
||||
|
||||
If no folder is attached, ask the user to drag the feature folder into the conversation.
|
||||
|
||||
### 2. Read GitHub References
|
||||
|
||||
Parse `github.md` to extract:
|
||||
|
||||
- `feature_name` from frontmatter
|
||||
- `epic_issue` number from frontmatter
|
||||
- `repository` from frontmatter
|
||||
|
||||
If `github.md` doesn't exist, inform the user:
|
||||
|
||||
> "This feature hasn't been published to GitHub yet. Run `/publish-to-github` first to create the GitHub issues and project."
|
||||
|
||||
### 3. Query Open Tasks
|
||||
|
||||
List all open issues for this feature:
|
||||
|
||||
```bash
|
||||
gh issue list \
|
||||
--label "feature/{feature_name}" \
|
||||
--state open \
|
||||
--json number,title,body,labels \
|
||||
--limit 100
|
||||
```
|
||||
|
||||
### 4. Parse and Sort Tasks
|
||||
|
||||
For each issue returned:
|
||||
|
||||
1. Extract the `Sequence` number from the issue body (format: `**Sequence**: N`)
|
||||
2. Extract dependencies from the issue body (format: `**Depends on**: #X, #Y` or `None`)
|
||||
3. Skip the Epic issue (has label `epic`)
|
||||
|
||||
### 5. Check Dependencies
|
||||
|
||||
For each potential task:
|
||||
|
||||
1. Parse its dependencies
|
||||
2. Check if all dependency issues are closed: `gh issue view {dep-number} --json state -q .state`
|
||||
3. A task is "available" if all its dependencies are `CLOSED`
|
||||
|
||||
### 6. Select Next Task
|
||||
|
||||
From all available (unblocked) tasks, select the one with the **lowest sequence number**.
|
||||
|
||||
If no tasks are available:
|
||||
|
||||
- If all tasks are closed: Report "🎉 All tasks for {feature_name} are complete!"
|
||||
- If tasks exist but are blocked: Report which tasks are blocked and by what
|
||||
|
||||
### 7. Display Task Information
|
||||
|
||||
Before implementing, show:
|
||||
|
||||
```
|
||||
📋 Next Task: #{number} - {title}
|
||||
|
||||
Phase: {phase}
|
||||
Sequence: {sequence}
|
||||
Dependencies: {deps or "None"}
|
||||
|
||||
## Task Description
|
||||
{task description from issue body}
|
||||
|
||||
Proceeding with implementation...
|
||||
```
|
||||
|
||||
### 8. Set Issue Status to "In Progress"
|
||||
|
||||
Before starting implementation, update the issue status on the GitHub Project board. This is **required** when `project_number` exists in `github.md`.
|
||||
|
||||
**IMPORTANT**: Do NOT rely on labels like "status/in-progress" as they may not exist in the repository. Always update the Project board status directly.
|
||||
|
||||
#### Step 8.1: Add a comment indicating work has started
|
||||
|
||||
```bash
|
||||
gh issue comment {issue-number} --repo {repository} --body "🚀 **Status Update**: Implementation started
|
||||
|
||||
Working on this task now..."
|
||||
```
|
||||
|
||||
#### Step 8.2: Get the project item ID for this issue
|
||||
|
||||
```bash
|
||||
gh project item-list {project_number} --owner {owner} --format json
|
||||
```
|
||||
|
||||
Parse the JSON output to find the item where `content.number` matches your issue number. Extract the `id` field - this is the `{item_id}`.
|
||||
|
||||
Example: For issue #8, find the item with `"content": {"number": 8, ...}` and note its `"id"` value (e.g., `"PVTI_lAHOBLPcNM4BJm9zzgh_JP0"`).
|
||||
|
||||
#### Step 8.3: Get the Status field ID and option IDs
|
||||
|
||||
```bash
|
||||
gh project field-list {project_number} --owner {owner} --format json
|
||||
```
|
||||
|
||||
From the output, find the field with `"name": "Status"`. Extract:
|
||||
|
||||
- `id` - this is the `{status_field_id}` (e.g., `"PVTSSF_lAHOBLPcNM4BJm9zzg5uLNA"`)
|
||||
- `options` array - find the option with `"name": "In Progress"` and note its `id` as `{in_progress_option_id}` (e.g., `"47fc9ee4"`)
|
||||
|
||||
#### Step 8.4: Construct the project ID
|
||||
|
||||
The project ID follows the pattern `PVT_kwHO{owner_id}M4{project_suffix}`. You can derive it from the item IDs which contain the same pattern, or use:
|
||||
|
||||
```bash
|
||||
gh project view {project_number} --owner {owner} --format json
|
||||
```
|
||||
|
||||
#### Step 8.5: Update the project item status to "In Progress"
|
||||
|
||||
```bash
|
||||
gh project item-edit \
|
||||
--project-id {project_id} \
|
||||
--id {item_id} \
|
||||
--field-id {status_field_id} \
|
||||
--single-select-option-id {in_progress_option_id}
|
||||
```
|
||||
|
||||
**Complete Example** (with real values from a session):
|
||||
|
||||
```bash
|
||||
# Step 8.1: Comment on the issue
|
||||
gh issue comment 8 --repo leonvanzyl/json-anything --body "🚀 **Status Update**: Implementation started
|
||||
|
||||
Working on this task now..."
|
||||
|
||||
# Step 8.2: Get item ID (parse JSON to find item with content.number == 8)
|
||||
gh project item-list 3 --owner leonvanzyl --format json
|
||||
# Found: "id": "PVTI_lAHOBLPcNM4BJm9zzgh_JP0"
|
||||
|
||||
# Step 8.3: Get field IDs (find Status field and "In Progress" option)
|
||||
gh project field-list 3 --owner leonvanzyl --format json
|
||||
# Found Status field: "id": "PVTSSF_lAHOBLPcNM4BJm9zzg5uLNA"
|
||||
# Found "In Progress" option: "id": "47fc9ee4"
|
||||
|
||||
# Step 8.5: Update status
|
||||
gh project item-edit \
|
||||
--project-id PVT_kwHOBLPcNM4BJm9z \
|
||||
--id PVTI_lAHOBLPcNM4BJm9zzgh_JP0 \
|
||||
--field-id PVTSSF_lAHOBLPcNM4BJm9zzg5uLNA \
|
||||
--single-select-option-id 47fc9ee4
|
||||
```
|
||||
|
||||
**Note**: The `gh project item-edit` command returns no output on success. Verify the update worked by checking the project board or re-running `gh project item-list`.
|
||||
|
||||
### 9. Read Full Context
|
||||
|
||||
Before implementing:
|
||||
|
||||
1. Read the Epic issue for overall context: `gh issue view {epic_issue}`
|
||||
2. Read `requirements.md` for feature requirements
|
||||
3. Review relevant parts of the codebase based on the task
|
||||
|
||||
### 10. Implement the Task
|
||||
|
||||
Implement the task following project conventions:
|
||||
|
||||
- Follow existing code patterns in the codebase
|
||||
- Use the `@/` import alias
|
||||
- Run `pnpm lint && pnpm typecheck` after making changes
|
||||
- Fix any lint or type errors before committing
|
||||
|
||||
### 11. Commit Changes
|
||||
|
||||
After successful implementation:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat: {task title} (closes #{issue-number})"
|
||||
```
|
||||
|
||||
The `closes #{issue-number}` syntax will automatically close the issue when pushed/merged.
|
||||
|
||||
### 12. Update Issue with Implementation Details
|
||||
|
||||
After committing, update the GitHub issue with comprehensive details about what was implemented:
|
||||
|
||||
```bash
|
||||
# Update the issue with implementation summary
|
||||
gh issue comment {issue-number} --body "✅ **Implementation Complete**
|
||||
|
||||
## Changes Made
|
||||
- **Files Modified**: {list of files changed}
|
||||
- **Files Added**: {list of new files, if any}
|
||||
|
||||
## Summary of Changes
|
||||
{detailed description of what was implemented}
|
||||
|
||||
## Technical Details
|
||||
{any relevant technical notes, decisions made, or patterns followed}
|
||||
|
||||
## Testing
|
||||
- Lint: ✅ Passed
|
||||
- TypeCheck: ✅ Passed
|
||||
{any manual testing performed}
|
||||
|
||||
---
|
||||
Commit: {commit-hash}
|
||||
Ready for review and merge."
|
||||
```
|
||||
|
||||
**Note**: Do NOT try to update labels like "status/done" as they may not exist in the repository. The Project board status update in Step 13 is the authoritative status indicator.
|
||||
|
||||
### 13. Update Project Board (if applicable)
|
||||
|
||||
If the feature has an associated GitHub Project board, update the status to "Done". You should already have the `{item_id}`, `{status_field_id}`, and `{project_id}` from Step 8.
|
||||
|
||||
From the field list obtained in Step 8.3, find the option with `"name": "Done"` and note its `id` as `{done_option_id}` (e.g., `"98236657"`).
|
||||
|
||||
```bash
|
||||
gh project item-edit \
|
||||
--project-id {project_id} \
|
||||
--id {item_id} \
|
||||
--field-id {status_field_id} \
|
||||
--single-select-option-id {done_option_id}
|
||||
```
|
||||
|
||||
**Complete Example** (continuing from Step 8):
|
||||
|
||||
```bash
|
||||
# Using the same IDs from Step 8, but with "Done" option ID
|
||||
gh project item-edit \
|
||||
--project-id PVT_kwHOBLPcNM4BJm9z \
|
||||
--id PVTI_lAHOBLPcNM4BJm9zzgh_JP0 \
|
||||
--field-id PVTSSF_lAHOBLPcNM4BJm9zzg5uLNA \
|
||||
--single-select-option-id 98236657
|
||||
```
|
||||
|
||||
**Note**: The command returns no output on success.
|
||||
|
||||
### 14. Report Completion
|
||||
|
||||
After completing the task:
|
||||
|
||||
```
|
||||
✅ Task #{number} complete: {title}
|
||||
|
||||
GitHub Updates:
|
||||
- Issue #{number} status: "Done" ✅
|
||||
- Project board: Updated ✅ (if applicable)
|
||||
- Implementation details: Added to issue ✅
|
||||
|
||||
Changes made:
|
||||
- {summary of files changed}
|
||||
- {summary of functionality added}
|
||||
|
||||
Next steps:
|
||||
- Push changes: `git push`
|
||||
- Or continue: Drop the feature folder again and say "continue"
|
||||
|
||||
Remaining tasks: {count} open, {count} blocked
|
||||
```
|
||||
|
||||
### 15. Prompt for Next Action
|
||||
|
||||
Ask the user:
|
||||
|
||||
> "Would you like me to continue with the next task, or would you prefer to review the changes first?"
|
||||
|
||||
If the user wants to continue, repeat from step 3.
|
||||
|
||||
## Handling Edge Cases
|
||||
|
||||
### No github.md file
|
||||
|
||||
```
|
||||
❌ This feature hasn't been published to GitHub.
|
||||
|
||||
To publish, run: /publish-to-github
|
||||
|
||||
Or if you want to continue without GitHub integration, I can work from
|
||||
the implementation-plan.md file directly. Would you like to do that instead?
|
||||
```
|
||||
|
||||
### All tasks complete
|
||||
|
||||
```
|
||||
🎉 Congratulations! All tasks for "{feature_name}" are complete!
|
||||
|
||||
Epic: https://github.com/{repository}/issues/{epic_issue}
|
||||
|
||||
You can close the Epic issue with:
|
||||
gh issue close {epic_issue}
|
||||
```
|
||||
|
||||
### All remaining tasks are blocked
|
||||
|
||||
```
|
||||
⏸️ All remaining tasks are currently blocked.
|
||||
|
||||
Blocked tasks:
|
||||
- #{number} "{title}" - blocked by #{dep} (still open)
|
||||
- ...
|
||||
|
||||
To unblock, complete these dependencies first, or manually close them if
|
||||
they're no longer needed.
|
||||
```
|
||||
|
||||
### Implementation fails lint/typecheck
|
||||
|
||||
```
|
||||
⚠️ Implementation has lint/type errors:
|
||||
|
||||
{error output}
|
||||
|
||||
Please review and fix these issues before I can commit. Would you like me
|
||||
to attempt to fix them?
|
||||
```
|
||||
|
||||
## Offline Mode (No GitHub)
|
||||
|
||||
If the user prefers not to use GitHub or gh is unavailable, fall back to the
|
||||
implementation-plan.md approach:
|
||||
|
||||
1. Read `implementation-plan.md`
|
||||
2. Find the first unchecked task `[ ]`
|
||||
3. Implement it
|
||||
4. Check off the task in the markdown file
|
||||
5. Commit with a descriptive message
|
||||
|
||||
This maintains backward compatibility with the original workflow.
|
||||
|
||||
## Notes
|
||||
|
||||
- Only implement ONE task per invocation unless the user explicitly asks for more
|
||||
- Always run lint and typecheck before committing
|
||||
- Preserve the task's acceptance criteria when checking completion
|
||||
- If a task is unclear, ask for clarification rather than guessing
|
||||
@@ -1,11 +1,89 @@
|
||||
---
|
||||
description: create feature
|
||||
description: Create a new feature with requirements and implementation plan
|
||||
---
|
||||
|
||||
# Given the above conversation:
|
||||
# Create Feature
|
||||
|
||||
- Store the requirements and implementation plan in /specs. Create a new sub folder for this feature. The implementation plan should be split into phases with actionable tasks for each phase. Each tasks should have a checkbox so we can keep track of our progress - example [ ] Task description.
|
||||
This command creates a new feature specification folder with requirements and implementation plan documents.
|
||||
|
||||
- Exclude unit and e2e testing from the implementation plan, UNLESS the user clearly asks for it to be included.
|
||||
## Instructions
|
||||
|
||||
- IF no conversation exists and the implementation plan is not clear, then ask the user what the requirements are first and then create the spec sub-folder, requirements and implementation plan .md files.
|
||||
### Given the above conversation:
|
||||
|
||||
1. **Create feature folder**
|
||||
- Store the requirements and implementation plan in `/specs`
|
||||
- Create a new subfolder for this feature using kebab-case (e.g., `add-auth`)
|
||||
|
||||
2. **Create requirements.md**
|
||||
- Document what the feature does and why
|
||||
- Include acceptance criteria
|
||||
- Reference any related features or dependencies
|
||||
|
||||
3. **Create implementation-plan.md**
|
||||
- Split the implementation into phases
|
||||
- Create actionable tasks for each phase
|
||||
- Each task should have a checkbox: `[ ] Task description`
|
||||
- Tasks should be specific enough for an agent to implement independently
|
||||
- Include dependencies between tasks where relevant
|
||||
|
||||
4. **Exclude testing tasks**
|
||||
- Do NOT include unit or e2e testing tasks
|
||||
- UNLESS the user explicitly asks for testing to be included
|
||||
|
||||
### If no conversation exists:
|
||||
|
||||
Ask the user what the requirements are first, then create the spec subfolder with:
|
||||
|
||||
- `requirements.md`
|
||||
- `implementation-plan.md`
|
||||
|
||||
## Implementation Plan Format
|
||||
|
||||
Use this structure for `implementation-plan.md`:
|
||||
|
||||
```markdown
|
||||
# Implementation Plan: {Feature Name}
|
||||
|
||||
## Overview
|
||||
|
||||
Brief summary of what will be built.
|
||||
|
||||
## Phase 1: {Phase Name}
|
||||
|
||||
{Brief description of this phase's goal}
|
||||
|
||||
### Tasks
|
||||
|
||||
- [ ] Task 1 description
|
||||
- [ ] Task 2 description (depends on Task 1)
|
||||
- [ ] Task 3 description
|
||||
|
||||
## Phase 2: {Phase Name}
|
||||
|
||||
{Brief description}
|
||||
|
||||
### Tasks
|
||||
|
||||
- [ ] Task 4 description (depends on Phase 1)
|
||||
- [ ] Task 5 description
|
||||
...
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
After creating the feature, inform the user:
|
||||
|
||||
> Feature specification created at `specs/{feature-name}/`
|
||||
>
|
||||
> **Next steps:**
|
||||
>
|
||||
> 1. Review the requirements and implementation plan
|
||||
> 2. Run `/publish-to-github` to create GitHub issues and project
|
||||
> 3. Use `/continue-feature` or drag the folder into a conversation to start implementing
|
||||
|
||||
## Notes
|
||||
|
||||
- Keep tasks atomic - each should be implementable in a single session
|
||||
- Tasks should produce working, testable code when complete
|
||||
- Use clear, descriptive task names that explain what will be done
|
||||
- Note dependencies explicitly when tasks must be done in order
|
||||
|
||||
238
.claude/commands/publish-to-github.md
Normal file
238
.claude/commands/publish-to-github.md
Normal file
@@ -0,0 +1,238 @@
|
||||
---
|
||||
description: Publish a feature from /specs to GitHub Issues and Projects
|
||||
---
|
||||
|
||||
# Publish Feature to GitHub
|
||||
|
||||
This command publishes a feature from the /specs folder to GitHub, creating:
|
||||
|
||||
- An Epic issue containing the full requirements
|
||||
- Individual task issues for each item in the implementation plan
|
||||
- A GitHub Project to track progress
|
||||
- Labels for organization and sequencing
|
||||
- A `github.md` file in the specs folder with all references
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- The GitHub CLI (`gh`) must be authenticated: `gh auth status`
|
||||
- The GitHub CLI must have project scopes: Token scopes should include `project` and `read:project`. If missing, run: `gh auth refresh -s project,read:project`
|
||||
- A feature folder must exist in /specs with `requirements.md` and `implementation-plan.md`
|
||||
|
||||
## Instructions
|
||||
|
||||
### 1. Identify the Feature
|
||||
|
||||
Look for the feature folder attached to the conversation or specified by the user.
|
||||
The folder should be at `/specs/{feature-name}/` and contain:
|
||||
|
||||
- `requirements.md` - Feature requirements
|
||||
- `implementation-plan.md` - Task breakdown with phases
|
||||
|
||||
If no folder is specified, ask the user which feature to publish.
|
||||
|
||||
### 2. Extract Feature Information
|
||||
|
||||
- **Feature name**: Use the folder name (e.g., `answer-scoring`)
|
||||
- **Feature title**: Parse the main heading from `requirements.md`
|
||||
- **Tasks**: Parse all checkbox items from `implementation-plan.md`, noting their phase
|
||||
|
||||
### 3. Get Repository Information
|
||||
|
||||
Run: `gh repo view --json nameWithOwner,owner -q '.nameWithOwner + " " + .owner.login'`
|
||||
|
||||
This returns both values, e.g., `leonvanzyl/json-anything leonvanzyl`
|
||||
|
||||
Store the results as:
|
||||
|
||||
- `{repository}` - Full repo name (e.g., `leonvanzyl/json-anything`)
|
||||
- `{owner}` - Repository owner (e.g., `leonvanzyl`)
|
||||
|
||||
### 4. Create Labels (if they don't exist)
|
||||
|
||||
```bash
|
||||
gh label create "epic" --color "7057ff" --description "Feature epic" 2>/dev/null || true
|
||||
gh label create "feature/{feature-name}" --color "0E8A16" --description "Feature: {feature-title}" 2>/dev/null || true
|
||||
gh label create "phase-1" --color "C5DEF5" --description "Phase 1 tasks" 2>/dev/null || true
|
||||
gh label create "phase-2" --color "BFD4F2" --description "Phase 2 tasks" 2>/dev/null || true
|
||||
gh label create "phase-3" --color "A2C4E0" --description "Phase 3 tasks" 2>/dev/null || true
|
||||
```
|
||||
|
||||
### 5. Create the Epic Issue
|
||||
|
||||
Create an Epic issue with the full requirements:
|
||||
|
||||
```bash
|
||||
gh issue create \
|
||||
--title "Epic: {Feature Title}" \
|
||||
--label "epic" \
|
||||
--label "feature/{feature-name}" \
|
||||
--body-file specs/{feature-name}/requirements.md
|
||||
```
|
||||
|
||||
Capture the issue number from the output (e.g., `#100`).
|
||||
|
||||
### 6. Create Task Issues
|
||||
|
||||
For each task in the implementation plan, create an issue:
|
||||
|
||||
**Issue body template:**
|
||||
|
||||
```markdown
|
||||
## Context
|
||||
|
||||
Part of Epic: #{epic-number}
|
||||
|
||||
## Task
|
||||
|
||||
{Task description from implementation plan}
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Implementation complete
|
||||
- [ ] Code passes lint and typecheck
|
||||
- [ ] Changes follow project conventions
|
||||
|
||||
## Metadata
|
||||
|
||||
- **Sequence**: {sequence-number}
|
||||
- **Depends on**: {comma-separated list of dependency issue numbers, or "None"}
|
||||
- **Phase**: {phase-number}
|
||||
```
|
||||
|
||||
**Command:**
|
||||
|
||||
```bash
|
||||
gh issue create \
|
||||
--title "{Task description}" \
|
||||
--label "feature/{feature-name}" \
|
||||
--label "phase-{n}" \
|
||||
--body "{issue-body}"
|
||||
```
|
||||
|
||||
Capture each issue number to build the dependency chain.
|
||||
|
||||
### 7. Update Epic with Task List
|
||||
|
||||
Edit the Epic issue to include a task list linking all sub-issues:
|
||||
|
||||
```bash
|
||||
gh issue edit {epic-number} --body "{original-body}
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### Phase 1
|
||||
- [ ] #{task-1-number} {task-1-title}
|
||||
- [ ] #{task-2-number} {task-2-title}
|
||||
|
||||
### Phase 2
|
||||
- [ ] #{task-3-number} {task-3-title}
|
||||
...
|
||||
"
|
||||
```
|
||||
|
||||
### 8. Create GitHub Project and Link to Repository
|
||||
|
||||
Create the project under the repository owner:
|
||||
|
||||
```bash
|
||||
gh project create --title "Feature: {Feature Title}" --owner {owner}
|
||||
```
|
||||
|
||||
Note: If the project already exists or the user prefers to use an existing project, skip this step. You can list projects with: `gh project list --owner {owner}`
|
||||
|
||||
Capture the project number from the output (you may need to run `gh project list --owner {owner}` to get it).
|
||||
|
||||
Then link the project to the repository so it appears in the repo's Projects tab:
|
||||
|
||||
```bash
|
||||
gh project link {project-number} --owner {owner} --repo {repository}
|
||||
```
|
||||
|
||||
### 9. Add Issues to Project
|
||||
|
||||
```bash
|
||||
gh project item-add {project-number} --owner {owner} --url "https://github.com/{repository}/issues/{epic-number}"
|
||||
gh project item-add {project-number} --owner {owner} --url "https://github.com/{repository}/issues/{task-1-number}"
|
||||
# ... repeat for all task issues
|
||||
```
|
||||
|
||||
### 10. Create github.md
|
||||
|
||||
Create `specs/{feature-name}/github.md` with all the GitHub references:
|
||||
|
||||
```markdown
|
||||
---
|
||||
feature_name: { feature-name }
|
||||
feature_title: { Feature Title }
|
||||
repository: { repository }
|
||||
epic_issue: { epic-number }
|
||||
project_number: { project-number }
|
||||
labels:
|
||||
- epic
|
||||
- feature/{feature-name}
|
||||
published_at: { current-date }
|
||||
---
|
||||
|
||||
# GitHub References
|
||||
|
||||
This feature has been published to GitHub.
|
||||
|
||||
## Links
|
||||
|
||||
- [Epic Issue](https://github.com/{repository}/issues/{epic-number})
|
||||
- [Project Board](https://github.com/users/{owner}/projects/{project-number}) (also linked to repository)
|
||||
|
||||
## Task Issues
|
||||
|
||||
| # | Title | Phase | Status |
|
||||
| --------- | ------- | ----- | ------ |
|
||||
| #{task-1} | {title} | 1 | Open |
|
||||
| #{task-2} | {title} | 1 | Open |
|
||||
| ... | ... | ... | ... |
|
||||
|
||||
## Labels
|
||||
|
||||
- `epic` - Feature epic marker
|
||||
- `feature/{feature-name}` - Feature-specific label
|
||||
- `phase-1`, `phase-2`, `phase-3` - Phase markers
|
||||
```
|
||||
|
||||
### 11. Report Summary
|
||||
|
||||
After completion, report:
|
||||
|
||||
- Epic issue URL
|
||||
- Number of task issues created
|
||||
- Project board URL
|
||||
- Location of github.md file
|
||||
|
||||
Example output:
|
||||
|
||||
```
|
||||
Feature "{Feature Title}" published to GitHub!
|
||||
|
||||
Epic: https://github.com/{repository}/issues/{epic-number}
|
||||
Project: https://github.com/users/{owner}/projects/{project-number} (linked to repo)
|
||||
Tasks created: 8
|
||||
|
||||
The github.md file has been created at specs/{feature-name}/github.md
|
||||
|
||||
To continue implementing, drag the specs/{feature-name}/ folder into a new conversation
|
||||
and say "continue with this feature" or use /continue-feature.
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
- If `gh auth status` fails, inform user to run `gh auth login`
|
||||
- If project creation fails with "missing required scopes [project read:project]", inform user to run `gh auth refresh -s project,read:project`
|
||||
- If the feature folder doesn't exist, ask user to run `/create-feature` first
|
||||
- If labels/issues fail to create, report the error and continue with remaining items
|
||||
- If github.md already exists, ask user if they want to overwrite or update it
|
||||
|
||||
## Notes
|
||||
|
||||
- Task sequence numbers should be assigned based on order within phases (Phase 1 tasks get 1, 2, 3, etc., Phase 2 continues from there)
|
||||
- Dependencies within the same phase are generally sequential
|
||||
- Cross-phase dependencies should be explicit in the implementation plan
|
||||
4
create-agentic-app/package-lock.json
generated
4
create-agentic-app/package-lock.json
generated
@@ -1,12 +1,12 @@
|
||||
{
|
||||
"name": "create-agentic-app",
|
||||
"version": "1.1.24",
|
||||
"version": "1.1.25",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "create-agentic-app",
|
||||
"version": "1.1.24",
|
||||
"version": "1.1.25",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"chalk": "^5.3.0",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "create-agentic-app",
|
||||
"version": "1.1.24",
|
||||
"version": "1.1.25",
|
||||
"description": "Scaffold a new agentic AI application with Next.js, Better Auth, and AI SDK",
|
||||
"type": "module",
|
||||
"bin": {
|
||||
|
||||
355
create-agentic-app/template/.claude/commands/continue-feature.md
Normal file
355
create-agentic-app/template/.claude/commands/continue-feature.md
Normal file
@@ -0,0 +1,355 @@
|
||||
---
|
||||
description: Continue implementing the next task for a GitHub-published feature
|
||||
---
|
||||
|
||||
# Continue Feature Implementation
|
||||
|
||||
This command finds and implements the next available task for a feature that has been published to GitHub.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- The GitHub CLI (`gh`) must be authenticated
|
||||
- The feature must have been published to GitHub (github.md exists in the feature folder)
|
||||
- The feature folder should be attached to the conversation
|
||||
|
||||
## Instructions
|
||||
|
||||
### 1. Locate the Feature
|
||||
|
||||
Look for the feature folder attached to the conversation. It should be at `/specs/{feature-name}/` and contain:
|
||||
|
||||
- `requirements.md` - Feature requirements (for context)
|
||||
- `implementation-plan.md` - Original task breakdown
|
||||
- `github.md` - GitHub references (required)
|
||||
|
||||
If no folder is attached, ask the user to drag the feature folder into the conversation.
|
||||
|
||||
### 2. Read GitHub References
|
||||
|
||||
Parse `github.md` to extract:
|
||||
|
||||
- `feature_name` from frontmatter
|
||||
- `epic_issue` number from frontmatter
|
||||
- `repository` from frontmatter
|
||||
|
||||
If `github.md` doesn't exist, inform the user:
|
||||
|
||||
> "This feature hasn't been published to GitHub yet. Run `/publish-to-github` first to create the GitHub issues and project."
|
||||
|
||||
### 3. Query Open Tasks
|
||||
|
||||
List all open issues for this feature:
|
||||
|
||||
```bash
|
||||
gh issue list \
|
||||
--label "feature/{feature_name}" \
|
||||
--state open \
|
||||
--json number,title,body,labels \
|
||||
--limit 100
|
||||
```
|
||||
|
||||
### 4. Parse and Sort Tasks
|
||||
|
||||
For each issue returned:
|
||||
|
||||
1. Extract the `Sequence` number from the issue body (format: `**Sequence**: N`)
|
||||
2. Extract dependencies from the issue body (format: `**Depends on**: #X, #Y` or `None`)
|
||||
3. Skip the Epic issue (has label `epic`)
|
||||
|
||||
### 5. Check Dependencies
|
||||
|
||||
For each potential task:
|
||||
|
||||
1. Parse its dependencies
|
||||
2. Check if all dependency issues are closed: `gh issue view {dep-number} --json state -q .state`
|
||||
3. A task is "available" if all its dependencies are `CLOSED`
|
||||
|
||||
### 6. Select Next Task
|
||||
|
||||
From all available (unblocked) tasks, select the one with the **lowest sequence number**.
|
||||
|
||||
If no tasks are available:
|
||||
|
||||
- If all tasks are closed: Report "🎉 All tasks for {feature_name} are complete!"
|
||||
- If tasks exist but are blocked: Report which tasks are blocked and by what
|
||||
|
||||
### 7. Display Task Information
|
||||
|
||||
Before implementing, show:
|
||||
|
||||
```
|
||||
📋 Next Task: #{number} - {title}
|
||||
|
||||
Phase: {phase}
|
||||
Sequence: {sequence}
|
||||
Dependencies: {deps or "None"}
|
||||
|
||||
## Task Description
|
||||
{task description from issue body}
|
||||
|
||||
Proceeding with implementation...
|
||||
```
|
||||
|
||||
### 8. Set Issue Status to "In Progress"
|
||||
|
||||
Before starting implementation, update the issue status on the GitHub Project board. This is **required** when `project_number` exists in `github.md`.
|
||||
|
||||
**IMPORTANT**: Do NOT rely on labels like "status/in-progress" as they may not exist in the repository. Always update the Project board status directly.
|
||||
|
||||
#### Step 8.1: Add a comment indicating work has started
|
||||
|
||||
```bash
|
||||
gh issue comment {issue-number} --repo {repository} --body "🚀 **Status Update**: Implementation started
|
||||
|
||||
Working on this task now..."
|
||||
```
|
||||
|
||||
#### Step 8.2: Get the project item ID for this issue
|
||||
|
||||
```bash
|
||||
gh project item-list {project_number} --owner {owner} --format json
|
||||
```
|
||||
|
||||
Parse the JSON output to find the item where `content.number` matches your issue number. Extract the `id` field - this is the `{item_id}`.
|
||||
|
||||
Example: For issue #8, find the item with `"content": {"number": 8, ...}` and note its `"id"` value (e.g., `"PVTI_lAHOBLPcNM4BJm9zzgh_JP0"`).
|
||||
|
||||
#### Step 8.3: Get the Status field ID and option IDs
|
||||
|
||||
```bash
|
||||
gh project field-list {project_number} --owner {owner} --format json
|
||||
```
|
||||
|
||||
From the output, find the field with `"name": "Status"`. Extract:
|
||||
|
||||
- `id` - this is the `{status_field_id}` (e.g., `"PVTSSF_lAHOBLPcNM4BJm9zzg5uLNA"`)
|
||||
- `options` array - find the option with `"name": "In Progress"` and note its `id` as `{in_progress_option_id}` (e.g., `"47fc9ee4"`)
|
||||
|
||||
#### Step 8.4: Construct the project ID
|
||||
|
||||
The project ID follows the pattern `PVT_kwHO{owner_id}M4{project_suffix}`. You can derive it from the item IDs which contain the same pattern, or use:
|
||||
|
||||
```bash
|
||||
gh project view {project_number} --owner {owner} --format json
|
||||
```
|
||||
|
||||
#### Step 8.5: Update the project item status to "In Progress"
|
||||
|
||||
```bash
|
||||
gh project item-edit \
|
||||
--project-id {project_id} \
|
||||
--id {item_id} \
|
||||
--field-id {status_field_id} \
|
||||
--single-select-option-id {in_progress_option_id}
|
||||
```
|
||||
|
||||
**Complete Example** (with real values from a session):
|
||||
|
||||
```bash
|
||||
# Step 8.1: Comment on the issue
|
||||
gh issue comment 8 --repo leonvanzyl/json-anything --body "🚀 **Status Update**: Implementation started
|
||||
|
||||
Working on this task now..."
|
||||
|
||||
# Step 8.2: Get item ID (parse JSON to find item with content.number == 8)
|
||||
gh project item-list 3 --owner leonvanzyl --format json
|
||||
# Found: "id": "PVTI_lAHOBLPcNM4BJm9zzgh_JP0"
|
||||
|
||||
# Step 8.3: Get field IDs (find Status field and "In Progress" option)
|
||||
gh project field-list 3 --owner leonvanzyl --format json
|
||||
# Found Status field: "id": "PVTSSF_lAHOBLPcNM4BJm9zzg5uLNA"
|
||||
# Found "In Progress" option: "id": "47fc9ee4"
|
||||
|
||||
# Step 8.5: Update status
|
||||
gh project item-edit \
|
||||
--project-id PVT_kwHOBLPcNM4BJm9z \
|
||||
--id PVTI_lAHOBLPcNM4BJm9zzgh_JP0 \
|
||||
--field-id PVTSSF_lAHOBLPcNM4BJm9zzg5uLNA \
|
||||
--single-select-option-id 47fc9ee4
|
||||
```
|
||||
|
||||
**Note**: The `gh project item-edit` command returns no output on success. Verify the update worked by checking the project board or re-running `gh project item-list`.
|
||||
|
||||
### 9. Read Full Context
|
||||
|
||||
Before implementing:
|
||||
|
||||
1. Read the Epic issue for overall context: `gh issue view {epic_issue}`
|
||||
2. Read `requirements.md` for feature requirements
|
||||
3. Review relevant parts of the codebase based on the task
|
||||
|
||||
### 10. Implement the Task
|
||||
|
||||
Implement the task following project conventions:
|
||||
|
||||
- Follow existing code patterns in the codebase
|
||||
- Use the `@/` import alias
|
||||
- Run `pnpm lint && pnpm typecheck` after making changes
|
||||
- Fix any lint or type errors before committing
|
||||
|
||||
### 11. Commit Changes
|
||||
|
||||
After successful implementation:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat: {task title} (closes #{issue-number})"
|
||||
```
|
||||
|
||||
The `closes #{issue-number}` syntax will automatically close the issue when pushed/merged.
|
||||
|
||||
### 12. Update Issue with Implementation Details
|
||||
|
||||
After committing, update the GitHub issue with comprehensive details about what was implemented:
|
||||
|
||||
```bash
|
||||
# Update the issue with implementation summary
|
||||
gh issue comment {issue-number} --body "✅ **Implementation Complete**
|
||||
|
||||
## Changes Made
|
||||
- **Files Modified**: {list of files changed}
|
||||
- **Files Added**: {list of new files, if any}
|
||||
|
||||
## Summary of Changes
|
||||
{detailed description of what was implemented}
|
||||
|
||||
## Technical Details
|
||||
{any relevant technical notes, decisions made, or patterns followed}
|
||||
|
||||
## Testing
|
||||
- Lint: ✅ Passed
|
||||
- TypeCheck: ✅ Passed
|
||||
{any manual testing performed}
|
||||
|
||||
---
|
||||
Commit: {commit-hash}
|
||||
Ready for review and merge."
|
||||
```
|
||||
|
||||
**Note**: Do NOT try to update labels like "status/done" as they may not exist in the repository. The Project board status update in Step 13 is the authoritative status indicator.
|
||||
|
||||
### 13. Update Project Board (if applicable)
|
||||
|
||||
If the feature has an associated GitHub Project board, update the status to "Done". You should already have the `{item_id}`, `{status_field_id}`, and `{project_id}` from Step 8.
|
||||
|
||||
From the field list obtained in Step 8.3, find the option with `"name": "Done"` and note its `id` as `{done_option_id}` (e.g., `"98236657"`).
|
||||
|
||||
```bash
|
||||
gh project item-edit \
|
||||
--project-id {project_id} \
|
||||
--id {item_id} \
|
||||
--field-id {status_field_id} \
|
||||
--single-select-option-id {done_option_id}
|
||||
```
|
||||
|
||||
**Complete Example** (continuing from Step 8):
|
||||
|
||||
```bash
|
||||
# Using the same IDs from Step 8, but with "Done" option ID
|
||||
gh project item-edit \
|
||||
--project-id PVT_kwHOBLPcNM4BJm9z \
|
||||
--id PVTI_lAHOBLPcNM4BJm9zzgh_JP0 \
|
||||
--field-id PVTSSF_lAHOBLPcNM4BJm9zzg5uLNA \
|
||||
--single-select-option-id 98236657
|
||||
```
|
||||
|
||||
**Note**: The command returns no output on success.
|
||||
|
||||
### 14. Report Completion
|
||||
|
||||
After completing the task:
|
||||
|
||||
```
|
||||
✅ Task #{number} complete: {title}
|
||||
|
||||
GitHub Updates:
|
||||
- Issue #{number} status: "Done" ✅
|
||||
- Project board: Updated ✅ (if applicable)
|
||||
- Implementation details: Added to issue ✅
|
||||
|
||||
Changes made:
|
||||
- {summary of files changed}
|
||||
- {summary of functionality added}
|
||||
|
||||
Next steps:
|
||||
- Push changes: `git push`
|
||||
- Or continue: Drop the feature folder again and say "continue"
|
||||
|
||||
Remaining tasks: {count} open, {count} blocked
|
||||
```
|
||||
|
||||
### 15. Prompt for Next Action
|
||||
|
||||
Ask the user:
|
||||
|
||||
> "Would you like me to continue with the next task, or would you prefer to review the changes first?"
|
||||
|
||||
If the user wants to continue, repeat from step 3.
|
||||
|
||||
## Handling Edge Cases
|
||||
|
||||
### No github.md file
|
||||
|
||||
```
|
||||
❌ This feature hasn't been published to GitHub.
|
||||
|
||||
To publish, run: /publish-to-github
|
||||
|
||||
Or if you want to continue without GitHub integration, I can work from
|
||||
the implementation-plan.md file directly. Would you like to do that instead?
|
||||
```
|
||||
|
||||
### All tasks complete
|
||||
|
||||
```
|
||||
🎉 Congratulations! All tasks for "{feature_name}" are complete!
|
||||
|
||||
Epic: https://github.com/{repository}/issues/{epic_issue}
|
||||
|
||||
You can close the Epic issue with:
|
||||
gh issue close {epic_issue}
|
||||
```
|
||||
|
||||
### All remaining tasks are blocked
|
||||
|
||||
```
|
||||
⏸️ All remaining tasks are currently blocked.
|
||||
|
||||
Blocked tasks:
|
||||
- #{number} "{title}" - blocked by #{dep} (still open)
|
||||
- ...
|
||||
|
||||
To unblock, complete these dependencies first, or manually close them if
|
||||
they're no longer needed.
|
||||
```
|
||||
|
||||
### Implementation fails lint/typecheck
|
||||
|
||||
```
|
||||
⚠️ Implementation has lint/type errors:
|
||||
|
||||
{error output}
|
||||
|
||||
Please review and fix these issues before I can commit. Would you like me
|
||||
to attempt to fix them?
|
||||
```
|
||||
|
||||
## Offline Mode (No GitHub)
|
||||
|
||||
If the user prefers not to use GitHub or gh is unavailable, fall back to the
|
||||
implementation-plan.md approach:
|
||||
|
||||
1. Read `implementation-plan.md`
|
||||
2. Find the first unchecked task `[ ]`
|
||||
3. Implement it
|
||||
4. Check off the task in the markdown file
|
||||
5. Commit with a descriptive message
|
||||
|
||||
This maintains backward compatibility with the original workflow.
|
||||
|
||||
## Notes
|
||||
|
||||
- Only implement ONE task per invocation unless the user explicitly asks for more
|
||||
- Always run lint and typecheck before committing
|
||||
- Preserve the task's acceptance criteria when checking completion
|
||||
- If a task is unclear, ask for clarification rather than guessing
|
||||
@@ -1,11 +1,89 @@
|
||||
---
|
||||
description: create feature
|
||||
description: Create a new feature with requirements and implementation plan
|
||||
---
|
||||
|
||||
# Given the above conversation:
|
||||
# Create Feature
|
||||
|
||||
- Store the requirements and implementation plan in /specs. Create a new sub folder for this feature. The implementation plan should be split into phases with actionable tasks for each phase. Each tasks should have a checkbox so we can keep track of our progress - example [ ] Task description.
|
||||
This command creates a new feature specification folder with requirements and implementation plan documents.
|
||||
|
||||
- Exclude unit and e2e testing from the implementation plan, UNLESS the user clearly asks for it to be included.
|
||||
## Instructions
|
||||
|
||||
- IF no conversation exists and the implementation plan is not clear, then ask the user what the requirements are first and then create the spec sub-folder, requirements and implementation plan .md files.
|
||||
### Given the above conversation:
|
||||
|
||||
1. **Create feature folder**
|
||||
- Store the requirements and implementation plan in `/specs`
|
||||
- Create a new subfolder for this feature using kebab-case (e.g., `add-auth`)
|
||||
|
||||
2. **Create requirements.md**
|
||||
- Document what the feature does and why
|
||||
- Include acceptance criteria
|
||||
- Reference any related features or dependencies
|
||||
|
||||
3. **Create implementation-plan.md**
|
||||
- Split the implementation into phases
|
||||
- Create actionable tasks for each phase
|
||||
- Each task should have a checkbox: `[ ] Task description`
|
||||
- Tasks should be specific enough for an agent to implement independently
|
||||
- Include dependencies between tasks where relevant
|
||||
|
||||
4. **Exclude testing tasks**
|
||||
- Do NOT include unit or e2e testing tasks
|
||||
- UNLESS the user explicitly asks for testing to be included
|
||||
|
||||
### If no conversation exists:
|
||||
|
||||
Ask the user what the requirements are first, then create the spec subfolder with:
|
||||
|
||||
- `requirements.md`
|
||||
- `implementation-plan.md`
|
||||
|
||||
## Implementation Plan Format
|
||||
|
||||
Use this structure for `implementation-plan.md`:
|
||||
|
||||
```markdown
|
||||
# Implementation Plan: {Feature Name}
|
||||
|
||||
## Overview
|
||||
|
||||
Brief summary of what will be built.
|
||||
|
||||
## Phase 1: {Phase Name}
|
||||
|
||||
{Brief description of this phase's goal}
|
||||
|
||||
### Tasks
|
||||
|
||||
- [ ] Task 1 description
|
||||
- [ ] Task 2 description (depends on Task 1)
|
||||
- [ ] Task 3 description
|
||||
|
||||
## Phase 2: {Phase Name}
|
||||
|
||||
{Brief description}
|
||||
|
||||
### Tasks
|
||||
|
||||
- [ ] Task 4 description (depends on Phase 1)
|
||||
- [ ] Task 5 description
|
||||
...
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
After creating the feature, inform the user:
|
||||
|
||||
> Feature specification created at `specs/{feature-name}/`
|
||||
>
|
||||
> **Next steps:**
|
||||
>
|
||||
> 1. Review the requirements and implementation plan
|
||||
> 2. Run `/publish-to-github` to create GitHub issues and project
|
||||
> 3. Use `/continue-feature` or drag the folder into a conversation to start implementing
|
||||
|
||||
## Notes
|
||||
|
||||
- Keep tasks atomic - each should be implementable in a single session
|
||||
- Tasks should produce working, testable code when complete
|
||||
- Use clear, descriptive task names that explain what will be done
|
||||
- Note dependencies explicitly when tasks must be done in order
|
||||
|
||||
@@ -0,0 +1,238 @@
|
||||
---
|
||||
description: Publish a feature from /specs to GitHub Issues and Projects
|
||||
---
|
||||
|
||||
# Publish Feature to GitHub
|
||||
|
||||
This command publishes a feature from the /specs folder to GitHub, creating:
|
||||
|
||||
- An Epic issue containing the full requirements
|
||||
- Individual task issues for each item in the implementation plan
|
||||
- A GitHub Project to track progress
|
||||
- Labels for organization and sequencing
|
||||
- A `github.md` file in the specs folder with all references
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- The GitHub CLI (`gh`) must be authenticated: `gh auth status`
|
||||
- The GitHub CLI must have project scopes: Token scopes should include `project` and `read:project`. If missing, run: `gh auth refresh -s project,read:project`
|
||||
- A feature folder must exist in /specs with `requirements.md` and `implementation-plan.md`
|
||||
|
||||
## Instructions
|
||||
|
||||
### 1. Identify the Feature
|
||||
|
||||
Look for the feature folder attached to the conversation or specified by the user.
|
||||
The folder should be at `/specs/{feature-name}/` and contain:
|
||||
|
||||
- `requirements.md` - Feature requirements
|
||||
- `implementation-plan.md` - Task breakdown with phases
|
||||
|
||||
If no folder is specified, ask the user which feature to publish.
|
||||
|
||||
### 2. Extract Feature Information
|
||||
|
||||
- **Feature name**: Use the folder name (e.g., `answer-scoring`)
|
||||
- **Feature title**: Parse the main heading from `requirements.md`
|
||||
- **Tasks**: Parse all checkbox items from `implementation-plan.md`, noting their phase
|
||||
|
||||
### 3. Get Repository Information
|
||||
|
||||
Run: `gh repo view --json nameWithOwner,owner -q '.nameWithOwner + " " + .owner.login'`
|
||||
|
||||
This returns both values, e.g., `leonvanzyl/json-anything leonvanzyl`
|
||||
|
||||
Store the results as:
|
||||
|
||||
- `{repository}` - Full repo name (e.g., `leonvanzyl/json-anything`)
|
||||
- `{owner}` - Repository owner (e.g., `leonvanzyl`)
|
||||
|
||||
### 4. Create Labels (if they don't exist)
|
||||
|
||||
```bash
|
||||
gh label create "epic" --color "7057ff" --description "Feature epic" 2>/dev/null || true
|
||||
gh label create "feature/{feature-name}" --color "0E8A16" --description "Feature: {feature-title}" 2>/dev/null || true
|
||||
gh label create "phase-1" --color "C5DEF5" --description "Phase 1 tasks" 2>/dev/null || true
|
||||
gh label create "phase-2" --color "BFD4F2" --description "Phase 2 tasks" 2>/dev/null || true
|
||||
gh label create "phase-3" --color "A2C4E0" --description "Phase 3 tasks" 2>/dev/null || true
|
||||
```
|
||||
|
||||
### 5. Create the Epic Issue
|
||||
|
||||
Create an Epic issue with the full requirements:
|
||||
|
||||
```bash
|
||||
gh issue create \
|
||||
--title "Epic: {Feature Title}" \
|
||||
--label "epic" \
|
||||
--label "feature/{feature-name}" \
|
||||
--body-file specs/{feature-name}/requirements.md
|
||||
```
|
||||
|
||||
Capture the issue number from the output (e.g., `#100`).
|
||||
|
||||
### 6. Create Task Issues
|
||||
|
||||
For each task in the implementation plan, create an issue:
|
||||
|
||||
**Issue body template:**
|
||||
|
||||
```markdown
|
||||
## Context
|
||||
|
||||
Part of Epic: #{epic-number}
|
||||
|
||||
## Task
|
||||
|
||||
{Task description from implementation plan}
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Implementation complete
|
||||
- [ ] Code passes lint and typecheck
|
||||
- [ ] Changes follow project conventions
|
||||
|
||||
## Metadata
|
||||
|
||||
- **Sequence**: {sequence-number}
|
||||
- **Depends on**: {comma-separated list of dependency issue numbers, or "None"}
|
||||
- **Phase**: {phase-number}
|
||||
```
|
||||
|
||||
**Command:**
|
||||
|
||||
```bash
|
||||
gh issue create \
|
||||
--title "{Task description}" \
|
||||
--label "feature/{feature-name}" \
|
||||
--label "phase-{n}" \
|
||||
--body "{issue-body}"
|
||||
```
|
||||
|
||||
Capture each issue number to build the dependency chain.
|
||||
|
||||
### 7. Update Epic with Task List
|
||||
|
||||
Edit the Epic issue to include a task list linking all sub-issues:
|
||||
|
||||
```bash
|
||||
gh issue edit {epic-number} --body "{original-body}
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### Phase 1
|
||||
- [ ] #{task-1-number} {task-1-title}
|
||||
- [ ] #{task-2-number} {task-2-title}
|
||||
|
||||
### Phase 2
|
||||
- [ ] #{task-3-number} {task-3-title}
|
||||
...
|
||||
"
|
||||
```
|
||||
|
||||
### 8. Create GitHub Project and Link to Repository
|
||||
|
||||
Create the project under the repository owner:
|
||||
|
||||
```bash
|
||||
gh project create --title "Feature: {Feature Title}" --owner {owner}
|
||||
```
|
||||
|
||||
Note: If the project already exists or the user prefers to use an existing project, skip this step. You can list projects with: `gh project list --owner {owner}`
|
||||
|
||||
Capture the project number from the output (you may need to run `gh project list --owner {owner}` to get it).
|
||||
|
||||
Then link the project to the repository so it appears in the repo's Projects tab:
|
||||
|
||||
```bash
|
||||
gh project link {project-number} --owner {owner} --repo {repository}
|
||||
```
|
||||
|
||||
### 9. Add Issues to Project
|
||||
|
||||
```bash
|
||||
gh project item-add {project-number} --owner {owner} --url "https://github.com/{repository}/issues/{epic-number}"
|
||||
gh project item-add {project-number} --owner {owner} --url "https://github.com/{repository}/issues/{task-1-number}"
|
||||
# ... repeat for all task issues
|
||||
```
|
||||
|
||||
### 10. Create github.md
|
||||
|
||||
Create `specs/{feature-name}/github.md` with all the GitHub references:
|
||||
|
||||
```markdown
|
||||
---
|
||||
feature_name: { feature-name }
|
||||
feature_title: { Feature Title }
|
||||
repository: { repository }
|
||||
epic_issue: { epic-number }
|
||||
project_number: { project-number }
|
||||
labels:
|
||||
- epic
|
||||
- feature/{feature-name}
|
||||
published_at: { current-date }
|
||||
---
|
||||
|
||||
# GitHub References
|
||||
|
||||
This feature has been published to GitHub.
|
||||
|
||||
## Links
|
||||
|
||||
- [Epic Issue](https://github.com/{repository}/issues/{epic-number})
|
||||
- [Project Board](https://github.com/users/{owner}/projects/{project-number}) (also linked to repository)
|
||||
|
||||
## Task Issues
|
||||
|
||||
| # | Title | Phase | Status |
|
||||
| --------- | ------- | ----- | ------ |
|
||||
| #{task-1} | {title} | 1 | Open |
|
||||
| #{task-2} | {title} | 1 | Open |
|
||||
| ... | ... | ... | ... |
|
||||
|
||||
## Labels
|
||||
|
||||
- `epic` - Feature epic marker
|
||||
- `feature/{feature-name}` - Feature-specific label
|
||||
- `phase-1`, `phase-2`, `phase-3` - Phase markers
|
||||
```
|
||||
|
||||
### 11. Report Summary
|
||||
|
||||
After completion, report:
|
||||
|
||||
- Epic issue URL
|
||||
- Number of task issues created
|
||||
- Project board URL
|
||||
- Location of github.md file
|
||||
|
||||
Example output:
|
||||
|
||||
```
|
||||
Feature "{Feature Title}" published to GitHub!
|
||||
|
||||
Epic: https://github.com/{repository}/issues/{epic-number}
|
||||
Project: https://github.com/users/{owner}/projects/{project-number} (linked to repo)
|
||||
Tasks created: 8
|
||||
|
||||
The github.md file has been created at specs/{feature-name}/github.md
|
||||
|
||||
To continue implementing, drag the specs/{feature-name}/ folder into a new conversation
|
||||
and say "continue with this feature" or use /continue-feature.
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
- If `gh auth status` fails, inform user to run `gh auth login`
|
||||
- If project creation fails with "missing required scopes [project read:project]", inform user to run `gh auth refresh -s project,read:project`
|
||||
- If the feature folder doesn't exist, ask user to run `/create-feature` first
|
||||
- If labels/issues fail to create, report the error and continue with remaining items
|
||||
- If github.md already exists, ask user if they want to overwrite or update it
|
||||
|
||||
## Notes
|
||||
|
||||
- Task sequence numbers should be assigned based on order within phases (Phase 1 tasks get 1, 2, 3, etc., Phase 2 continues from there)
|
||||
- Dependencies within the same phase are generally sequential
|
||||
- Cross-phase dependencies should be explicit in the implementation plan
|
||||
Reference in New Issue
Block a user