ros/agentic-coding-starter-kit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: change GitHub workflow from task-level to phase-level issues

Browse Source 
Update the feature workflow commands to create GitHub issues per phase
instead of per individual task. This reduces issue clutter while still
maintaining granular task tracking via checklists within phase issues.

Key changes:

**publish-to-github.md:**
- Create phase issues instead of individual task issues
- Each phase issue contains the full task checklist from implementation plan
- Add support for `[complex]` marker to break out complex tasks as separate issues
- Update Epic to link to phase issues instead of tasks
- Update github.md template to show phases and optional complex task issues

**create-feature.md:**
- Add documentation for `[complex]` task marker
- Update implementation plan format example with nested sub-tasks
- Add "When to Use [complex]" guidance section

**continue-feature.md:**
- Rewrite workflow to work with phase issues instead of task issues
- Add logic to identify current phase and find unchecked tasks
- Support both phase issue tasks and complex task issues
- Add step to update phase issue checklist after completing tasks
- Update completion reporting for phase-based progress
- Renumber steps (8.x → 7.x) for consistency

**Hybrid approach:**
- Default: one issue per phase with task checklists
- Optional: break out tasks marked `[complex]` or with nested sub-tasks
- Complex task issues link back to parent phase issue

This change results in ~5 issues (1 epic + 4 phases) instead of ~47 issues
for a typical feature, significantly reducing GitHub issue noise.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Leon van Zyl
2025-12-03 14:23:35 +02:00
parent 9332df2253
commit 732744802a
8 changed files with 481 additions and 193 deletions
Download Patch File Download Diff File Expand all files Collapse all files

181
.claude/commands/continue-feature.md
View File

@@ -36,7 +36,7 @@ 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
### 3. Query Open Issues
List all open issues for this feature:
@@ -48,41 +48,58 @@ gh issue list \
--limit 100
```
### 4. Parse and Sort Tasks
### 4. Identify Current Phase
For each issue returned:
From the issues 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`)
1. Skip the Epic issue (has label `epic`)
2. Identify phase issues by title format: `Phase N: {Phase Title}`
3. Identify any complex task issues (non-epic, non-phase issues)
4. Sort phase issues by phase number (Phase 1 before Phase 2, etc.)
### 5. Check Dependencies
### 5. Select Next Work Item
For each potential task:
**Priority order:**
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`
1. **Complex task issues first**: If there are open complex task issues belonging to the current phase, work on the one with the lowest issue number
2. **Phase issue tasks**: Otherwise, look at the earliest open phase issue and find the first unchecked task in its checklist
### 6. Select Next Task
**To find the next task in a phase issue:**
From all available (unblocked) tasks, select the one with the **lowest sequence number**.
1. Read the phase issue body
2. Parse the `## Tasks` section
3. Find the first unchecked item: `- [ ]` (not `- [x]`)
4. If all tasks are checked, the phase is complete - close it and move to next phase
If no tasks are available:
If no work is 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
- If all phases are closed: Report "🎉 All tasks for {feature_name} are complete!"
- If current phase has all tasks checked: Close the phase issue and continue to next phase
### 7. Display Task Information
### 6. Display Task Information
Before implementing, show:
```
📋 Next Task: #{number} - {title}
**For a task from a phase issue:**
Phase: {phase}
Sequence: {sequence}
Dependencies: {deps or "None"}
```
📋 Next Task: {task description}
Phase: {phase number} - {phase title}
Issue: #{phase-issue-number}
Task: {task number} of {total tasks in phase}
Proceeding with implementation...
```
**For a complex task issue:**
```
📋 Next Task: #{issue-number} - {title}
Phase: {phase number}
Type: Complex task (separate issue)
Parent Phase Issue: #{phase-issue-number}
## Task Description
{task description from issue body}
@@ -90,13 +107,15 @@ Dependencies: {deps or "None"}
Proceeding with implementation...
```
### 8. Set Issue Status to "In Progress"
### 7. 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`.
**Note:** Update the phase issue (or complex task issue if working on one) to "In Progress".
**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
#### Step 7a: Add a comment indicating work has started
```bash
gh issue comment {issue-number} --repo {repository} --body "🚀 **Status Update**: Implementation started
@@ -104,7 +123,7 @@ gh issue comment {issue-number} --repo {repository} --body "🚀 **Status Update
Working on this task now..."
```
#### Step 8.2: Get the project item ID for this issue
#### Step 7b: Get the project item ID for this issue
```bash
gh project item-list {project_number} --owner {owner} --format json
@@ -114,7 +133,7 @@ Parse the JSON output to find the item where `content.number` matches your issue
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
#### Step 7c: Get the Status field ID and option IDs
```bash
gh project field-list {project_number} --owner {owner} --format json
@@ -125,7 +144,7 @@ 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
#### Step 7d: 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:
@@ -133,7 +152,7 @@ The project ID follows the pattern `PVT_kwHO{owner_id}M4{project_suffix}`. You c
gh project view {project_number} --owner {owner} --format json
```
#### Step 8.5: Update the project item status to "In Progress"
#### Step 7e: Update the project item status to "In Progress"
```bash
gh project item-edit \
@@ -146,21 +165,21 @@ gh project item-edit \
**Complete Example** (with real values from a session):
```bash
# Step 8.1: Comment on the issue
# Step 7a: 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)
# Step 7b: 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)
# Step 7c: 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
# Step 7e: Update status
gh project item-edit \
--project-id PVT_kwHOBLPcNM4BJm9z \
--id PVTI_lAHOBLPcNM4BJm9zzgh_JP0 \
@@ -170,7 +189,7 @@ gh project item-edit \
**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
### 8. Read Full Context
Before implementing:
@@ -178,7 +197,7 @@ Before implementing:
2. Read `requirements.md` for feature requirements
3. Review relevant parts of the codebase based on the task
### 10. Implement the Task
### 9. Implement the Task
Implement the task following project conventions:
@@ -187,16 +206,39 @@ Implement the task following project conventions:
- Run `pnpm lint && pnpm typecheck` after making changes
- Fix any lint or type errors before committing
### 11. Commit Changes
### 10. Commit Changes
After successful implementation:
```bash
git add .
git commit -m "feat: {task title} (closes #{issue-number})"
git commit -m "feat: {task title}"
```
The `closes #{issue-number}` syntax will automatically close the issue when pushed/merged.
**Note:** For phase issues, we don't auto-close with `closes #` since the phase has multiple tasks. For complex task issues, you can use `closes #{issue-number}`.
### 11. Update Phase Issue Checklist
**For tasks from a phase issue**, update the phase issue body to check off the completed task:
```bash
# Get current issue body
gh issue view {phase-issue-number} --json body -q .body > /tmp/issue-body.md
# Edit the file to change "- [ ] {task}" to "- [x] {task}"
# Then update the issue
gh issue edit {phase-issue-number} --body-file /tmp/issue-body.md
```
Alternatively, add a comment noting the task completion:
```bash
gh issue comment {phase-issue-number} --body "✅ Completed: {task description}
Commit: {commit-hash}"
```
**For complex task issues**, the issue can be closed directly after implementation.
### 12. Update Issue with Implementation Details
@@ -228,11 +270,17 @@ 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)
### 13. Update Project Board and Close Phase (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.
If the feature has an associated GitHub Project board, update the status. You should already have the `{item_id}`, `{status_field_id}`, and `{project_id}` from Step 7.
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"`).
**For complex task issues:** Update status to "Done" and close the issue.
**For phase issues:**
- If more tasks remain in the phase, keep status as "In Progress"
- If all tasks in the phase are complete, update status to "Done" and close the phase issue
From the field list obtained in Step 7c, find the option with `"name": "Done"` and note its `id` as `{done_option_id}` (e.g., `"98236657"`).
```bash
gh project item-edit \
@@ -242,10 +290,10 @@ gh project item-edit \
--single-select-option-id {done_option_id}
```
**Complete Example** (continuing from Step 8):
**Complete Example** (continuing from Step 7):
```bash
# Using the same IDs from Step 8, but with "Done" option ID
# Using the same IDs from Step 7, but with "Done" option ID
gh project item-edit \
--project-id PVT_kwHOBLPcNM4BJm9z \
--id PVTI_lAHOBLPcNM4BJm9zzgh_JP0 \
@@ -259,13 +307,17 @@ gh project item-edit \
After completing the task:
**For a task from a phase issue:**
```
✅ Task #{number} complete: {title}
✅ Task complete: {task description}
Phase: {phase number} - {phase title} (#{phase-issue-number})
Progress: {completed}/{total} tasks in this phase
GitHub Updates:
- Issue #{number} status: "Done" ✅
- Project board: Updated ✅ (if applicable)
- Implementation details: Added to issue ✅
- Phase issue checklist: Updated ✅
- Implementation details: Added as comment ✅
Changes made:
- {summary of files changed}
@@ -275,7 +327,26 @@ Next steps:
- Push changes: `git push`
- Or continue: Drop the feature folder again and say "continue"
Remaining tasks: {count} open, {count} blocked
Phase status: {X} tasks remaining in current phase
```
**For a complex task issue:**
```
✅ Task #{issue-number} complete: {title}
GitHub Updates:
- Issue #{issue-number}: Closed ✅
- Project board: Updated to "Done" ✅
- 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"
```
### 15. Prompt for Next Action
@@ -299,10 +370,10 @@ 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
### All phases complete
```
🎉 Congratulations! All tasks for "{feature_name}" are complete!
🎉 Congratulations! All phases for "{feature_name}" are complete!
Epic: https://github.com/{repository}/issues/{epic_issue}
@@ -310,17 +381,15 @@ You can close the Epic issue with:
gh issue close {epic_issue}
```
### All remaining tasks are blocked
### Phase complete, moving to next
```
⏸️ All remaining tasks are currently blocked.
✅ Phase {n} complete! All tasks finished.
Blocked tasks:
- #{number} "{title}" - blocked by #{dep} (still open)
- ...
Closing Phase {n} issue...
Moving to Phase {n+1}: {Phase Title}
To unblock, complete these dependencies first, or manually close them if
they're no longer needed.
{Display next task from new phase}
```
### Implementation fails lint/typecheck

17
.claude/commands/create-feature.md
View File

@@ -25,6 +25,7 @@ This command creates a new feature specification folder with requirements and im
- 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
- Mark complex tasks with `[complex]` suffix (these will get their own GitHub issue when published)
4. **Create action-required.md**
- Extract all manual steps that require human action
@@ -64,7 +65,9 @@ Brief summary of what will be built.
- [ ] Task 1 description
- [ ] Task 2 description (depends on Task 1)
- [ ] Task 3 description
- [ ] Task 3 description [complex]
- [ ] Sub-task 3a
- [ ] Sub-task 3b
## Phase 2: {Phase Name}
@@ -77,6 +80,8 @@ Brief summary of what will be built.
...
```
**Note:** Tasks marked with `[complex]` or containing nested sub-tasks will be created as separate GitHub issues when published (linked to their parent phase issue).
## action-required.md Format
Use this structure for `action-required.md`:
@@ -135,3 +140,13 @@ After creating the feature, inform the user:
- Use clear, descriptive task names that explain what will be done
- Note dependencies explicitly when tasks must be done in order
- Common manual tasks: account creation, API key generation, environment variables, OAuth app configuration, DNS/domain setup, billing setup, third-party service registration
### When to Use `[complex]`
Mark a task with `[complex]` when it:
- Has multiple sub-tasks that need individual tracking
- Requires significant architectural decisions or discussion
- Spans multiple files or systems
- Would benefit from its own GitHub issue for comments/review
Most tasks should NOT be marked complex - reserve this for genuinely substantial work items.

136
.claude/commands/publish-to-github.md
View File

@@ -7,9 +7,9 @@ description: Publish a feature from /specs to GitHub Issues and Projects
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
- Phase issues for each phase in the implementation plan (with task checklists)
- A GitHub Project to track progress
- Labels for organization and sequencing
- Labels for organization
- A `github.md` file in the specs folder with all references
## Prerequisites
@@ -34,7 +34,7 @@ If no folder is specified, ask the user which feature to publish.
- **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
- **Phases**: Parse all phases from `implementation-plan.md`, including phase title, description, and task checklists
### 3. Get Repository Information
@@ -71,9 +71,9 @@ gh issue create \
Capture the issue number from the output (e.g., `#100`).
### 6. Create Task Issues
### 6. Create Phase Issues
For each task in the implementation plan, create an issue:
For each phase in the implementation plan, create an issue containing all tasks for that phase:
**Issue body template:**
@@ -82,52 +82,95 @@ For each task in the implementation plan, create an issue:
Part of Epic: #{epic-number}
## Task
## Overview
{Task description from implementation plan}
{Phase description/focus from implementation plan}
## Tasks
{Copy the full task checklist from the implementation plan for this phase, preserving markdown checkboxes}
## Acceptance Criteria
- [ ] Implementation complete
- [ ] All tasks in this phase completed
- [ ] 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}" \
--title "Phase {n}: {Phase Title}" \
--label "feature/{feature-name}" \
--label "phase-{n}" \
--body "{issue-body}"
```
Capture each issue number to build the dependency chain.
Capture each phase issue number for linking.
### 7. Update Epic with Task List
### 6a. Handle Complex Phases (Optional)
Edit the Epic issue to include a task list linking all sub-issues:
If a phase meets any of these criteria, consider breaking out individual tasks as separate issues:
- Phase has **more than 15 tasks**
- A task has **nested sub-tasks** (indented checkboxes)
- A task is marked with `[complex]` in the implementation plan
**For complex phases:**
1. Create the phase issue as normal (it becomes the parent)
2. For each complex task, create a separate task issue:
```bash
gh issue create \
--title "{Task description}" \
--label "feature/{feature-name}" \
--label "phase-{n}" \
--body "## Context
Part of Phase: #{phase-issue-number}
Part of Epic: #{epic-number}
## Task
{Task description with any sub-tasks}
## Acceptance Criteria
- [ ] Implementation complete
- [ ] Code passes lint and typecheck
- [ ] Changes follow project conventions"
```
3. Update the phase issue to replace the task checkbox with a linked issue reference:
**Before:**
```markdown
- [ ] Create complex authentication system [complex]
```
**After:**
```markdown
- [ ] #{task-issue-number} Create complex authentication system
```
This way the phase issue still tracks all work, but complex tasks get their own issue for detailed discussion and tracking.
### 7. Update Epic with Phase List
Edit the Epic issue to include a list linking all phase issues:
```bash
gh issue edit {epic-number} --body "{original-body}
---
## Tasks
## Phases
### Phase 1
- [ ] #{task-1-number} {task-1-title}
- [ ] #{task-2-number} {task-2-title}
### Phase 2
- [ ] #{task-3-number} {task-3-title}
- [ ] #{phase-1-number} Phase 1: {Phase 1 Title}
- [ ] #{phase-2-number} Phase 2: {Phase 2 Title}
- [ ] #{phase-3-number} Phase 3: {Phase 3 Title}
...
"
```
@@ -154,8 +197,9 @@ gh project link {project-number} --owner {owner} --repo {repository}
```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
gh project item-add {project-number} --owner {owner} --url "https://github.com/{repository}/issues/{phase-1-number}"
# ... repeat for all phase issues
# ... also add any complex task issues that were broken out
```
### 10. Create github.md
@@ -184,13 +228,22 @@ This feature has been published to GitHub.
- [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
## Phase Issues
| # | Title | Phase | Status |
| --------- | ------- | ----- | ------ |
| #{task-1} | {title} | 1 | Open |
| #{task-2} | {title} | 1 | Open |
| ... | ... | ... | ... |
| # | Title | Tasks | Status |
| ------------ | ------------------------ | ----- | ------ |
| #{phase-1} | Phase 1: {Phase 1 Title} | {n} | Open |
| #{phase-2} | Phase 2: {Phase 2 Title} | {n} | Open |
| ... | ... | ... | ... |
## Complex Task Issues (if any)
| # | Title | Phase | Status |
| ---------- | ------------ | ----- | ------ |
| #{task-1} | {Task title} | 1 | Open |
| ... | ... | ... | ... |
_(Omit this section if no complex tasks were broken out)_
## Labels
@@ -204,7 +257,9 @@ This feature has been published to GitHub.
After completion, report:
- Epic issue URL
- Number of task issues created
- Number of phase issues created
- Number of complex task issues created (if any)
- Total number of tasks across all phases
- Project board URL
- Location of github.md file
@@ -215,7 +270,9 @@ 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
Phases created: 4
Complex task issues: 2 (optional, only if any were created)
Total tasks: 46
The github.md file has been created at specs/{feature-name}/github.md
@@ -233,6 +290,9 @@ and say "continue with this feature" or use /continue-feature.
## 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
- Each phase issue contains the full task checklist from the implementation plan
- Tasks within a phase issue can be checked off as they're completed
- Phases should be executed sequentially (Phase 1 → Phase 2 → Phase 3, etc.)
- The Epic provides a high-level view with links to all phase issues
- Use the `[complex]` marker in implementation plans to flag tasks that need their own issue
- When breaking out complex tasks, the phase issue remains the parent tracker

4
create-agentic-app/package-lock.json generated
View File

@@ -1,12 +1,12 @@
{
"name": "create-agentic-app",
"version": "1.1.27",
"version": "1.1.28",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "create-agentic-app",
"version": "1.1.27",
"version": "1.1.28",
"license": "MIT",
"dependencies": {
"chalk": "^5.3.0",

2
create-agentic-app/package.json
View File

@@ -1,6 +1,6 @@
{
"name": "create-agentic-app",
"version": "1.1.27",
"version": "1.1.28",
"description": "Scaffold a new agentic AI application with Next.js, Better Auth, and AI SDK",
"type": "module",
"bin": {

181
create-agentic-app/template/.claude/commands/continue-feature.md
View File

@@ -36,7 +36,7 @@ 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
### 3. Query Open Issues
List all open issues for this feature:
@@ -48,41 +48,58 @@ gh issue list \
--limit 100
```
### 4. Parse and Sort Tasks
### 4. Identify Current Phase
For each issue returned:
From the issues 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`)
1. Skip the Epic issue (has label `epic`)
2. Identify phase issues by title format: `Phase N: {Phase Title}`
3. Identify any complex task issues (non-epic, non-phase issues)
4. Sort phase issues by phase number (Phase 1 before Phase 2, etc.)
### 5. Check Dependencies
### 5. Select Next Work Item
For each potential task:
**Priority order:**
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`
1. **Complex task issues first**: If there are open complex task issues belonging to the current phase, work on the one with the lowest issue number
2. **Phase issue tasks**: Otherwise, look at the earliest open phase issue and find the first unchecked task in its checklist
### 6. Select Next Task
**To find the next task in a phase issue:**
From all available (unblocked) tasks, select the one with the **lowest sequence number**.
1. Read the phase issue body
2. Parse the `## Tasks` section
3. Find the first unchecked item: `- [ ]` (not `- [x]`)
4. If all tasks are checked, the phase is complete - close it and move to next phase
If no tasks are available:
If no work is 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
- If all phases are closed: Report "🎉 All tasks for {feature_name} are complete!"
- If current phase has all tasks checked: Close the phase issue and continue to next phase
### 7. Display Task Information
### 6. Display Task Information
Before implementing, show:
```
📋 Next Task: #{number} - {title}
**For a task from a phase issue:**
Phase: {phase}
Sequence: {sequence}
Dependencies: {deps or "None"}
```
📋 Next Task: {task description}
Phase: {phase number} - {phase title}
Issue: #{phase-issue-number}
Task: {task number} of {total tasks in phase}
Proceeding with implementation...
```
**For a complex task issue:**
```
📋 Next Task: #{issue-number} - {title}
Phase: {phase number}
Type: Complex task (separate issue)
Parent Phase Issue: #{phase-issue-number}
## Task Description
{task description from issue body}
@@ -90,13 +107,15 @@ Dependencies: {deps or "None"}
Proceeding with implementation...
```
### 8. Set Issue Status to "In Progress"
### 7. 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`.
**Note:** Update the phase issue (or complex task issue if working on one) to "In Progress".
**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
#### Step 7a: Add a comment indicating work has started
```bash
gh issue comment {issue-number} --repo {repository} --body "🚀 **Status Update**: Implementation started
@@ -104,7 +123,7 @@ gh issue comment {issue-number} --repo {repository} --body "🚀 **Status Update
Working on this task now..."
```
#### Step 8.2: Get the project item ID for this issue
#### Step 7b: Get the project item ID for this issue
```bash
gh project item-list {project_number} --owner {owner} --format json
@@ -114,7 +133,7 @@ Parse the JSON output to find the item where `content.number` matches your issue
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
#### Step 7c: Get the Status field ID and option IDs
```bash
gh project field-list {project_number} --owner {owner} --format json
@@ -125,7 +144,7 @@ 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
#### Step 7d: 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:
@@ -133,7 +152,7 @@ The project ID follows the pattern `PVT_kwHO{owner_id}M4{project_suffix}`. You c
gh project view {project_number} --owner {owner} --format json
```
#### Step 8.5: Update the project item status to "In Progress"
#### Step 7e: Update the project item status to "In Progress"
```bash
gh project item-edit \
@@ -146,21 +165,21 @@ gh project item-edit \
**Complete Example** (with real values from a session):
```bash
# Step 8.1: Comment on the issue
# Step 7a: 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)
# Step 7b: 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)
# Step 7c: 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
# Step 7e: Update status
gh project item-edit \
--project-id PVT_kwHOBLPcNM4BJm9z \
--id PVTI_lAHOBLPcNM4BJm9zzgh_JP0 \
@@ -170,7 +189,7 @@ gh project item-edit \
**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
### 8. Read Full Context
Before implementing:
@@ -178,7 +197,7 @@ Before implementing:
2. Read `requirements.md` for feature requirements
3. Review relevant parts of the codebase based on the task
### 10. Implement the Task
### 9. Implement the Task
Implement the task following project conventions:
@@ -187,16 +206,39 @@ Implement the task following project conventions:
- Run `pnpm lint && pnpm typecheck` after making changes
- Fix any lint or type errors before committing
### 11. Commit Changes
### 10. Commit Changes
After successful implementation:
```bash
git add .
git commit -m "feat: {task title} (closes #{issue-number})"
git commit -m "feat: {task title}"
```
The `closes #{issue-number}` syntax will automatically close the issue when pushed/merged.
**Note:** For phase issues, we don't auto-close with `closes #` since the phase has multiple tasks. For complex task issues, you can use `closes #{issue-number}`.
### 11. Update Phase Issue Checklist
**For tasks from a phase issue**, update the phase issue body to check off the completed task:
```bash
# Get current issue body
gh issue view {phase-issue-number} --json body -q .body > /tmp/issue-body.md
# Edit the file to change "- [ ] {task}" to "- [x] {task}"
# Then update the issue
gh issue edit {phase-issue-number} --body-file /tmp/issue-body.md
```
Alternatively, add a comment noting the task completion:
```bash
gh issue comment {phase-issue-number} --body "✅ Completed: {task description}
Commit: {commit-hash}"
```
**For complex task issues**, the issue can be closed directly after implementation.
### 12. Update Issue with Implementation Details
@@ -228,11 +270,17 @@ 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)
### 13. Update Project Board and Close Phase (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.
If the feature has an associated GitHub Project board, update the status. You should already have the `{item_id}`, `{status_field_id}`, and `{project_id}` from Step 7.
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"`).
**For complex task issues:** Update status to "Done" and close the issue.
**For phase issues:**
- If more tasks remain in the phase, keep status as "In Progress"
- If all tasks in the phase are complete, update status to "Done" and close the phase issue
From the field list obtained in Step 7c, find the option with `"name": "Done"` and note its `id` as `{done_option_id}` (e.g., `"98236657"`).
```bash
gh project item-edit \
@@ -242,10 +290,10 @@ gh project item-edit \
--single-select-option-id {done_option_id}
```
**Complete Example** (continuing from Step 8):
**Complete Example** (continuing from Step 7):
```bash
# Using the same IDs from Step 8, but with "Done" option ID
# Using the same IDs from Step 7, but with "Done" option ID
gh project item-edit \
--project-id PVT_kwHOBLPcNM4BJm9z \
--id PVTI_lAHOBLPcNM4BJm9zzgh_JP0 \
@@ -259,13 +307,17 @@ gh project item-edit \
After completing the task:
**For a task from a phase issue:**
```
✅ Task #{number} complete: {title}
✅ Task complete: {task description}
Phase: {phase number} - {phase title} (#{phase-issue-number})
Progress: {completed}/{total} tasks in this phase
GitHub Updates:
- Issue #{number} status: "Done" ✅
- Project board: Updated ✅ (if applicable)
- Implementation details: Added to issue ✅
- Phase issue checklist: Updated ✅
- Implementation details: Added as comment ✅
Changes made:
- {summary of files changed}
@@ -275,7 +327,26 @@ Next steps:
- Push changes: `git push`
- Or continue: Drop the feature folder again and say "continue"
Remaining tasks: {count} open, {count} blocked
Phase status: {X} tasks remaining in current phase
```
**For a complex task issue:**
```
✅ Task #{issue-number} complete: {title}
GitHub Updates:
- Issue #{issue-number}: Closed ✅
- Project board: Updated to "Done" ✅
- 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"
```
### 15. Prompt for Next Action
@@ -299,10 +370,10 @@ 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
### All phases complete
```
🎉 Congratulations! All tasks for "{feature_name}" are complete!
🎉 Congratulations! All phases for "{feature_name}" are complete!
Epic: https://github.com/{repository}/issues/{epic_issue}
@@ -310,17 +381,15 @@ You can close the Epic issue with:
gh issue close {epic_issue}
```
### All remaining tasks are blocked
### Phase complete, moving to next
```
⏸️ All remaining tasks are currently blocked.
✅ Phase {n} complete! All tasks finished.
Blocked tasks:
- #{number} "{title}" - blocked by #{dep} (still open)
- ...
Closing Phase {n} issue...
Moving to Phase {n+1}: {Phase Title}
To unblock, complete these dependencies first, or manually close them if
they're no longer needed.
{Display next task from new phase}
```
### Implementation fails lint/typecheck

17
create-agentic-app/template/.claude/commands/create-feature.md
View File

@@ -25,6 +25,7 @@ This command creates a new feature specification folder with requirements and im
- 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
- Mark complex tasks with `[complex]` suffix (these will get their own GitHub issue when published)
4. **Create action-required.md**
- Extract all manual steps that require human action
@@ -64,7 +65,9 @@ Brief summary of what will be built.
- [ ] Task 1 description
- [ ] Task 2 description (depends on Task 1)
- [ ] Task 3 description
- [ ] Task 3 description [complex]
- [ ] Sub-task 3a
- [ ] Sub-task 3b
## Phase 2: {Phase Name}
@@ -77,6 +80,8 @@ Brief summary of what will be built.
...
```
**Note:** Tasks marked with `[complex]` or containing nested sub-tasks will be created as separate GitHub issues when published (linked to their parent phase issue).
## action-required.md Format
Use this structure for `action-required.md`:
@@ -135,3 +140,13 @@ After creating the feature, inform the user:
- Use clear, descriptive task names that explain what will be done
- Note dependencies explicitly when tasks must be done in order
- Common manual tasks: account creation, API key generation, environment variables, OAuth app configuration, DNS/domain setup, billing setup, third-party service registration
### When to Use `[complex]`
Mark a task with `[complex]` when it:
- Has multiple sub-tasks that need individual tracking
- Requires significant architectural decisions or discussion
- Spans multiple files or systems
- Would benefit from its own GitHub issue for comments/review
Most tasks should NOT be marked complex - reserve this for genuinely substantial work items.

136
create-agentic-app/template/.claude/commands/publish-to-github.md
View File

@@ -7,9 +7,9 @@ description: Publish a feature from /specs to GitHub Issues and Projects
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
- Phase issues for each phase in the implementation plan (with task checklists)
- A GitHub Project to track progress
- Labels for organization and sequencing
- Labels for organization
- A `github.md` file in the specs folder with all references
## Prerequisites
@@ -34,7 +34,7 @@ If no folder is specified, ask the user which feature to publish.
- **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
- **Phases**: Parse all phases from `implementation-plan.md`, including phase title, description, and task checklists
### 3. Get Repository Information
@@ -71,9 +71,9 @@ gh issue create \
Capture the issue number from the output (e.g., `#100`).
### 6. Create Task Issues
### 6. Create Phase Issues
For each task in the implementation plan, create an issue:
For each phase in the implementation plan, create an issue containing all tasks for that phase:
**Issue body template:**
@@ -82,52 +82,95 @@ For each task in the implementation plan, create an issue:
Part of Epic: #{epic-number}
## Task
## Overview
{Task description from implementation plan}
{Phase description/focus from implementation plan}
## Tasks
{Copy the full task checklist from the implementation plan for this phase, preserving markdown checkboxes}
## Acceptance Criteria
- [ ] Implementation complete
- [ ] All tasks in this phase completed
- [ ] 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}" \
--title "Phase {n}: {Phase Title}" \
--label "feature/{feature-name}" \
--label "phase-{n}" \
--body "{issue-body}"
```
Capture each issue number to build the dependency chain.
Capture each phase issue number for linking.
### 7. Update Epic with Task List
### 6a. Handle Complex Phases (Optional)
Edit the Epic issue to include a task list linking all sub-issues:
If a phase meets any of these criteria, consider breaking out individual tasks as separate issues:
- Phase has **more than 15 tasks**
- A task has **nested sub-tasks** (indented checkboxes)
- A task is marked with `[complex]` in the implementation plan
**For complex phases:**
1. Create the phase issue as normal (it becomes the parent)
2. For each complex task, create a separate task issue:
```bash
gh issue create \
--title "{Task description}" \
--label "feature/{feature-name}" \
--label "phase-{n}" \
--body "## Context
Part of Phase: #{phase-issue-number}
Part of Epic: #{epic-number}
## Task
{Task description with any sub-tasks}
## Acceptance Criteria
- [ ] Implementation complete
- [ ] Code passes lint and typecheck
- [ ] Changes follow project conventions"
```
3. Update the phase issue to replace the task checkbox with a linked issue reference:
**Before:**
```markdown
- [ ] Create complex authentication system [complex]
```
**After:**
```markdown
- [ ] #{task-issue-number} Create complex authentication system
```
This way the phase issue still tracks all work, but complex tasks get their own issue for detailed discussion and tracking.
### 7. Update Epic with Phase List
Edit the Epic issue to include a list linking all phase issues:
```bash
gh issue edit {epic-number} --body "{original-body}
---
## Tasks
## Phases
### Phase 1
- [ ] #{task-1-number} {task-1-title}
- [ ] #{task-2-number} {task-2-title}
### Phase 2
- [ ] #{task-3-number} {task-3-title}
- [ ] #{phase-1-number} Phase 1: {Phase 1 Title}
- [ ] #{phase-2-number} Phase 2: {Phase 2 Title}
- [ ] #{phase-3-number} Phase 3: {Phase 3 Title}
...
"
```
@@ -154,8 +197,9 @@ gh project link {project-number} --owner {owner} --repo {repository}
```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
gh project item-add {project-number} --owner {owner} --url "https://github.com/{repository}/issues/{phase-1-number}"
# ... repeat for all phase issues
# ... also add any complex task issues that were broken out
```
### 10. Create github.md
@@ -184,13 +228,22 @@ This feature has been published to GitHub.
- [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
## Phase Issues
| # | Title | Phase | Status |
| --------- | ------- | ----- | ------ |
| #{task-1} | {title} | 1 | Open |
| #{task-2} | {title} | 1 | Open |
| ... | ... | ... | ... |
| # | Title | Tasks | Status |
| ------------ | ------------------------ | ----- | ------ |
| #{phase-1} | Phase 1: {Phase 1 Title} | {n} | Open |
| #{phase-2} | Phase 2: {Phase 2 Title} | {n} | Open |
| ... | ... | ... | ... |
## Complex Task Issues (if any)
| # | Title | Phase | Status |
| ---------- | ------------ | ----- | ------ |
| #{task-1} | {Task title} | 1 | Open |
| ... | ... | ... | ... |
_(Omit this section if no complex tasks were broken out)_
## Labels
@@ -204,7 +257,9 @@ This feature has been published to GitHub.
After completion, report:
- Epic issue URL
- Number of task issues created
- Number of phase issues created
- Number of complex task issues created (if any)
- Total number of tasks across all phases
- Project board URL
- Location of github.md file
@@ -215,7 +270,9 @@ 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
Phases created: 4
Complex task issues: 2 (optional, only if any were created)
Total tasks: 46
The github.md file has been created at specs/{feature-name}/github.md
@@ -233,6 +290,9 @@ and say "continue with this feature" or use /continue-feature.
## 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
- Each phase issue contains the full task checklist from the implementation plan
- Tasks within a phase issue can be checked off as they're completed
- Phases should be executed sequentially (Phase 1 → Phase 2 → Phase 3, etc.)
- The Epic provides a high-level view with links to all phase issues
- Use the `[complex]` marker in implementation plans to flag tasks that need their own issue
- When breaking out complex tasks, the phase issue remains the parent tracker