diff --git a/.claude/commands/continue-feature.md b/.claude/commands/continue-feature.md new file mode 100644 index 0000000..51d9f28 --- /dev/null +++ b/.claude/commands/continue-feature.md @@ -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 diff --git a/.claude/commands/create-feature.md b/.claude/commands/create-feature.md index dac142d..af5eb71 100644 --- a/.claude/commands/create-feature.md +++ b/.claude/commands/create-feature.md @@ -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 diff --git a/.claude/commands/publish-to-github.md b/.claude/commands/publish-to-github.md new file mode 100644 index 0000000..de2e28d --- /dev/null +++ b/.claude/commands/publish-to-github.md @@ -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 diff --git a/create-agentic-app/package-lock.json b/create-agentic-app/package-lock.json index d3fa599..4e7f36a 100644 --- a/create-agentic-app/package-lock.json +++ b/create-agentic-app/package-lock.json @@ -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", diff --git a/create-agentic-app/package.json b/create-agentic-app/package.json index 0aba4a0..872cf0f 100644 --- a/create-agentic-app/package.json +++ b/create-agentic-app/package.json @@ -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": { diff --git a/create-agentic-app/template/.claude/commands/continue-feature.md b/create-agentic-app/template/.claude/commands/continue-feature.md new file mode 100644 index 0000000..51d9f28 --- /dev/null +++ b/create-agentic-app/template/.claude/commands/continue-feature.md @@ -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 diff --git a/create-agentic-app/template/.claude/commands/create-feature.md b/create-agentic-app/template/.claude/commands/create-feature.md index dac142d..af5eb71 100644 --- a/create-agentic-app/template/.claude/commands/create-feature.md +++ b/create-agentic-app/template/.claude/commands/create-feature.md @@ -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 diff --git a/create-agentic-app/template/.claude/commands/publish-to-github.md b/create-agentic-app/template/.claude/commands/publish-to-github.md new file mode 100644 index 0000000..de2e28d --- /dev/null +++ b/create-agentic-app/template/.claude/commands/publish-to-github.md @@ -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