diff --git a/.claude/commands/finish.md b/.claude/commands/finish.md new file mode 100644 index 0000000000..340a0c3804 --- /dev/null +++ b/.claude/commands/finish.md @@ -0,0 +1,228 @@ +# Finish and Cleanup + +Complete development work by cleaning up ephemeral documents and preparing for merge. + +## Description + +This skill handles the end of a development workflow: +1. Extracts key information from PLAN.md +2. Updates the PR description with a summary +3. Removes ephemeral planning documents +4. Creates a cleanup commit +5. Optionally merges the PR + +## Usage + +``` +/finish # Cleanup and prepare for merge +/finish --merge # Cleanup and merge with squash +/finish --dry-run # Show what would happen without making changes +``` + +## Arguments + +- `--merge`: After cleanup, merge the PR using `gh pr merge --squash` +- `--dry-run`: Preview actions without executing them +- `--no-pr-update`: Skip updating PR description + +## Steps + +### 1. Verify Prerequisites + +Check that we're ready to finish: +- Confirm we're in a git worktree (not main branch) +- Check for PLAN.md existence +- Verify no uncommitted changes (or warn) +- Check for open PR on current branch + +```bash +# Check branch +git branch --show-current + +# Check for uncommitted changes +git status --porcelain + +# Check for open PR +gh pr view --json state,url 2>/dev/null +``` + +### 2. Extract Summary from PLAN.md + +Parse PLAN.md to extract: +- Title and objective +- Completed tasks +- Key notes/decisions + +**Summary format:** +```markdown +## Summary + +[Objective from PLAN.md] + +### Completed +- [x] Task 1 +- [x] Task 2 +- [x] Task 3 + +### Key Decisions +- [Notable items from Notes section] +``` + +### 3. Update PR Description + +Append or update the PR description with the summary: + +```bash +# Get current PR body +gh pr view --json body -q '.body' + +# Update PR with summary +gh pr edit --body "$(cat <<'EOF' +[Original body] + +--- + +## Work Summary + +[Extracted summary from PLAN.md] +EOF +)" +``` + +### 4. Remove Ephemeral Files + +Delete planning documents that shouldn't be merged: + +```bash +# Remove PLAN.md and any other ephemeral docs +git rm PLAN.md 2>/dev/null || true +git rm HANDOVER.md 2>/dev/null || true +``` + +### 5. Create Cleanup Commit + +```bash +git commit -m "chore: remove planning docs + +Cleanup ephemeral documents before merge. +See PR description for work summary." +``` + +### 6. Push Changes + +```bash +git push +``` + +### 7. Merge (if --merge flag) + +```bash +gh pr merge --squash --delete-branch +``` + +## Edge Cases + +### No PLAN.md exists +- Warn user: "No PLAN.md found. Nothing to cleanup." +- Offer to proceed with merge anyway if --merge flag + +### Uncommitted changes +- Warn user about uncommitted changes +- Ask for confirmation before proceeding +- Suggest committing or stashing first + +### No open PR +- Skip PR update step +- Warn: "No open PR found for this branch" +- Still cleanup files if they exist + +### Incomplete tasks in PLAN.md +- Warn: "PLAN.md has X incomplete tasks" +- Show remaining tasks +- Ask for confirmation before proceeding + +## Examples + +### Example 1: Standard cleanup +``` +User: /finish + +Agent: +## Finishing development work + +### Prerequisites ✓ +- Branch: docs-v2-issue6763 +- PLAN.md: Found +- Uncommitted changes: None +- Open PR: #6789 + +### Summary extracted from PLAN.md: +- 4/4 tasks completed +- Objective: Document InfluxDB 3.9 release features + +### Actions: +1. ✓ Updated PR #6789 description with summary +2. ✓ Removed PLAN.md +3. ✓ Created commit: "chore: remove planning docs" +4. ✓ Pushed to origin + +Ready for merge! Run `/finish --merge` or merge manually. +``` + +### Example 2: Cleanup with merge +``` +User: /finish --merge + +Agent: +## Finishing development work + +[... same as above ...] + +5. ✓ Merged PR #6789 with squash +6. ✓ Deleted branch docs-v2-issue6763 + +Done! PR merged successfully. +``` + +### Example 3: Incomplete tasks warning +``` +User: /finish + +Agent: +## Finishing development work + +⚠️ Warning: PLAN.md has 2 incomplete tasks: +- [ ] Write unit tests +- [ ] Update documentation + +Are you sure you want to finish? (yes/no) + +User: yes + +Agent: Proceeding with cleanup... +[continues with normal flow] +``` + +### Example 4: Dry run +``` +User: /finish --dry-run + +Agent: +## Finish Preview (dry run) + +Would perform the following actions: +1. Update PR #6789 description with summary from PLAN.md +2. Run: git rm PLAN.md +3. Run: git commit -m "chore: remove planning docs" +4. Run: git push + +No changes made. Run `/finish` to execute. +``` + +## Notes + +- Always extracts summary before deleting PLAN.md +- Squash merge is recommended to keep main branch clean +- The deleted PLAN.md remains in branch history (recoverable if needed) +- Works with GitHub Actions cleanup as a fallback safety net +- Use `--no-pr-update` if you want to write the PR description manually diff --git a/.claude/commands/plan.md b/.claude/commands/plan.md new file mode 100644 index 0000000000..d99da4d905 --- /dev/null +++ b/.claude/commands/plan.md @@ -0,0 +1,184 @@ +# Plan Management + +Manage the PLAN.md planning document for the current worktree. + +## Description + +This skill manages ephemeral planning documents that track objectives, tasks, and notes during development. PLAN.md lives inside the git worktree, is tracked on the feature branch, and should be deleted before merging to main. + +## Usage + +``` +/plan # Display current PLAN.md +/plan create [issue-url] # Create new PLAN.md from template +/plan update # Update task status interactively +/plan status # Show task completion summary +``` + +## Subcommands + +### /plan (default: read) + +Display the current PLAN.md contents. If no PLAN.md exists, suggest creating one. + +**Steps:** +1. Check if PLAN.md exists in current directory +2. If exists: display contents with syntax highlighting +3. If not exists: inform user and suggest `/plan create` + +### /plan create [issue-url] + +Create a new PLAN.md from template. Optionally fetch issue/PR details from GitHub. + +**Arguments:** +- `issue-url` (optional): GitHub issue or PR URL to populate metadata + +**Steps:** +1. Check if PLAN.md already exists (warn if overwriting) +2. If issue-url provided: + - Parse org/repo/type/id from URL + - Fetch issue/PR details with `gh issue view` or `gh pr view` + - Populate Source section with metadata +3. If no issue-url: + - Create blank template with placeholders +4. Write PLAN.md to current directory +5. Display the created file + +**Template:** +```markdown +# [Title] + +## Source + +- **Repo**: [org/repo](https://github.com/org/repo) +- **Issue**: [#123](https://github.com/org/repo/issues/123) +- **Branch**: `branch-name` +- **Created**: YYYY-MM-DD + +## Objective + + + +## Tasks + +- [ ] Task 1 +- [ ] Task 2 + +## Notes + + +``` + +### /plan update + +Interactively update the PLAN.md - mark tasks complete, add notes, update objective. + +**Steps:** +1. Read current PLAN.md +2. Parse existing tasks (checkbox items) +3. Ask user what to update: + - Mark tasks as complete/incomplete + - Add new tasks + - Add notes to Notes section + - Update objective +4. Write updated PLAN.md +5. Show diff of changes + +### /plan status + +Show a summary of task completion status. + +**Steps:** +1. Read PLAN.md +2. Parse all checkbox items (`- [ ]` and `- [x]`) +3. Calculate completion stats +4. Display summary: + ``` + ## Plan Status + + **Progress:** 3/5 tasks complete (60%) + + ### Completed + - [x] Task 1 + - [x] Task 2 + - [x] Task 3 + + ### Remaining + - [ ] Task 4 + - [ ] Task 5 + ``` + +## Examples + +### Example 1: Create plan for GitHub issue +``` +User: /plan create https://github.com/influxdata/docs-v2/issues/6763 + +Agent: Created PLAN.md for issue #6763: "InfluxDB 3.9 Release Documentation" + +# ISSUE 6763: InfluxDB 3.9 Release Documentation + +## Source +- **Repo**: [influxdata/docs-v2](https://github.com/influxdata/docs-v2) +- **Issue**: [#6763](https://github.com/influxdata/docs-v2/issues/6763) +- **Branch**: `docs-v2-issue6763` +- **Created**: 2026-02-10 + +## Objective + + +## Tasks +- [ ] Task 1 +- [ ] Task 2 + +## Notes + +``` + +### Example 2: Check status +``` +User: /plan status + +Agent: +## Plan Status + +**Progress:** 2/4 tasks complete (50%) + +### Completed +- [x] Review issue requirements +- [x] Set up development environment + +### Remaining +- [ ] Implement feature +- [ ] Write tests +``` + +### Example 3: Update tasks +``` +User: /plan update + +Agent: Current tasks in PLAN.md: +1. [ ] Review issue requirements +2. [ ] Set up development environment +3. [ ] Implement feature +4. [ ] Write tests + +What would you like to update? +- Mark tasks complete (e.g., "1, 2") +- Add new task +- Add note + +User: Mark 1 and 2 complete, add note "Decided to use React for the UI" + +Agent: Updated PLAN.md: +- Marked "Review issue requirements" as complete +- Marked "Set up development environment" as complete +- Added note: "Decided to use React for the UI" +``` + +## Notes + +- PLAN.md is ephemeral - delete before merging to main +- Use `/finish` skill to properly cleanup and merge +- Tasks use standard markdown checkbox format: `- [ ]` and `- [x]` +- A startup hook can be configured to auto-inject PLAN.md at session start diff --git a/.github/workflows/cleanup-ephemeral-docs.yml b/.github/workflows/cleanup-ephemeral-docs.yml new file mode 100644 index 0000000000..58f0176412 --- /dev/null +++ b/.github/workflows/cleanup-ephemeral-docs.yml @@ -0,0 +1,103 @@ +# Cleanup Ephemeral Planning Documents +# +# This workflow automatically removes PLAN.md and other ephemeral planning +# documents when a PR is merged. This serves as a safety net in case the +# /finish skill wasn't used before merging. +# +# Ephemeral documents are temporary files used during development that +# shouldn't persist on the main branch: +# - PLAN.md: Planning and task tracking +# - HANDOVER.md: Session handover notes +# +# These files are tracked on feature branches but should be deleted before +# merge. If they slip through, this action cleans them up. +# +# Security Note: Uses pull_request_target to ensure write permissions for +# PRs from forks. This is safe because: +# 1. The workflow only checks out the base branch (not PR code) +# 2. File paths are validated (hardcoded list of allowed files) +# 3. No PR-controlled code is executed +# +# To use in your repo: +# 1. Copy this file to .github/workflows/cleanup-ephemeral-docs.yml +# 2. Update the 'branches' list to match your main branch (master or main) +# 3. Commit and push + +name: Cleanup ephemeral docs + +on: + pull_request_target: + types: [closed] + branches: + - master + - main + +jobs: + cleanup: + # Only run when PR is actually merged (not just closed) + if: github.event.pull_request.merged == true + runs-on: ubuntu-latest + + permissions: + contents: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + ref: ${{ github.event.pull_request.base.ref }} + fetch-depth: 0 + + - name: Check for ephemeral files + id: check + run: | + FILES_TO_REMOVE="" + + if [ -f "PLAN.md" ]; then + FILES_TO_REMOVE="$FILES_TO_REMOVE PLAN.md" + echo "Found: PLAN.md" + fi + + if [ -f "HANDOVER.md" ]; then + FILES_TO_REMOVE="$FILES_TO_REMOVE HANDOVER.md" + echo "Found: HANDOVER.md" + fi + + if [ -z "$FILES_TO_REMOVE" ]; then + echo "No ephemeral files found" + echo "has_files=false" >> $GITHUB_OUTPUT + else + echo "Files to remove:$FILES_TO_REMOVE" + echo "has_files=true" >> $GITHUB_OUTPUT + echo "files=$FILES_TO_REMOVE" >> $GITHUB_OUTPUT + fi + + - name: Remove ephemeral files + if: steps.check.outputs.has_files == 'true' + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + + # Pull latest changes to avoid non-fast-forward errors + # If rebase fails due to conflicts, fall back to regular merge + if ! git pull --rebase origin ${{ github.event.pull_request.base.ref }}; then + echo "Rebase failed, falling back to merge" + git rebase --abort + git pull --no-rebase --no-edit origin ${{ github.event.pull_request.base.ref }} + fi + + # Remove files + git rm -f ${{ steps.check.outputs.files }} + + # Commit with skip-ci to avoid triggering other workflows + git commit -m "chore: remove ephemeral planning docs [skip ci] + + Automated cleanup of development planning documents. + These files are used during development but shouldn't + persist on the main branch. + + Files removed:${{ steps.check.outputs.files }}" + + git push + + echo "✓ Removed ephemeral files and pushed cleanup commit" diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 0000000000..c4291ee41e --- /dev/null +++ b/PLAN.md @@ -0,0 +1,20 @@ +# jts-agentic-workflow + +## Source + +- **Project**: jts-agentic-workflow +- **Branch**: `docs-v2-jts-agentic-workflow` +- **Created**: 2026-02-10 + +## Objective + + + +## Tasks + +- [ ] Task 1 +- [ ] Task 2 + +## Notes + +