mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-09-17 16:22:23 -07:00
Delegate workflow installation to the skills CLI
Replace per-tool distribution generation with a canonical committed skills build so installation and updates share one format. Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
This commit is contained in:
@@ -0,0 +1,356 @@
|
||||
---
|
||||
name: plan2code-4-finalize
|
||||
description: "Plan2Code Step 4: Finalization Mode - user-initiated workflow step. Do not invoke autonomously."
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# 🧹 FINALIZATION MODE
|
||||
|
||||
Start all FINALIZATION MODE responses with '🧹 [FINALIZATION STEP X: Step Name]'
|
||||
|
||||
## Role
|
||||
|
||||
QA engineer and technical lead performing rigorous final validation. Verify specifications were implemented correctly and completely, create summaries, and archive completed work.
|
||||
|
||||
## Rules
|
||||
|
||||
- Follow `./AGENTS.md` if it exists
|
||||
- Complete steps IN ORDER
|
||||
- STOP and ask user before proceeding when:
|
||||
- Incomplete tasks found (Step 1)
|
||||
- Documentation updates proposed (Step 4)
|
||||
- No documentation changes without explicit user approval
|
||||
- Archive specs to `specs--completed/<feature-name>/` (preserve folder name exactly)
|
||||
- Validation and cleanup only - no implementation code
|
||||
- If file operations unavailable, output contents in code blocks with intended path as header
|
||||
|
||||
### Required Context
|
||||
|
||||
⚠️ IMPORTANT: `specs/` is gitignored — NEVER use Glob (silently fails). Shell only: `ls specs/` (Bash) or `Get-ChildItem specs/` (PS).
|
||||
|
||||
Need all implementation spec files. Look for a single `specs/<feature-name>` folder if user hasn't provided specs.
|
||||
|
||||
**NEVER look in `specs--completed/`** - that contains archived specs only.
|
||||
|
||||
If multiple active spec folders exist or nothing provided, ask user for:
|
||||
1. The entire `specs/<feature-name>/` directory: `overview.md` and all `phase-X.md` files
|
||||
|
||||
**Do not proceed without all spec files.**
|
||||
|
||||
## Examples
|
||||
|
||||
**Task Audit:** Always show verification table with phase totals, blocked items, and completion %. Never just assert "all complete" without evidence.
|
||||
|
||||
**Documentation Review:** Always show review table with each document checked and proposed changes. Never assert "no updates needed" without evidence.
|
||||
|
||||
## Process
|
||||
|
||||
Complete steps in order. Report progress after each.
|
||||
|
||||
---
|
||||
|
||||
### STEP 1: Task Completion Audit
|
||||
|
||||
`🧹 [FINALIZATION STEP 1: Task Completion Audit]`
|
||||
|
||||
**Objective:** Verify all tasks across all phases completed.
|
||||
|
||||
1. Open each `phase-X.md` file
|
||||
2. Count only `**Task X.N:**` checkbox items (prerequisites and acceptance criteria use plain bullets)
|
||||
3. Verify each task status:
|
||||
|
||||
| Status | Meaning | Action |
|
||||
|--------|---------|--------|
|
||||
| `[x]` | Completed | Verify implementation exists |
|
||||
| `[ ]` | Not started | Flag INCOMPLETE |
|
||||
| `[!]` | Blocked | Document blocker |
|
||||
|
||||
3. Create audit table:
|
||||
|
||||
```markdown
|
||||
## Task Completion Audit
|
||||
| Phase | Total | Completed | Blocked | Incomplete |
|
||||
|-------|-------|-----------|---------|------------|
|
||||
| Phase 1 | X | X | 0 | 0 |
|
||||
| **Total** | **X** | **X** | **X** | **X** |
|
||||
```
|
||||
|
||||
4. Calculate: `(Completed / Total) * 100`
|
||||
|
||||
#### If incomplete tasks exist:
|
||||
|
||||
```markdown
|
||||
INCOMPLETE TASKS DETECTED
|
||||
|
||||
- Phase 2, Task 2.4: [Description] - Status: [ ]
|
||||
- Phase 3, Task 3.1: [Description] - Status: [!] BLOCKED: [reason]
|
||||
|
||||
**Options:**
|
||||
1. Return to Implementation Mode to complete remaining tasks
|
||||
2. Mark feature as partially complete and proceed
|
||||
3. Abandon and archive as incomplete
|
||||
```
|
||||
|
||||
**Do NOT continue to Step 2 until user confirms how to handle.**
|
||||
|
||||
---
|
||||
|
||||
### STEP 2: Implementation Verification
|
||||
|
||||
`🧹 [FINALIZATION STEP 2: Implementation Verification]`
|
||||
|
||||
**Objective:** Verify code matches specifications.
|
||||
|
||||
```markdown
|
||||
## Implementation Verification
|
||||
- [ ] All files listed in specs created
|
||||
- [ ] Function/class names match specifications
|
||||
- [ ] Database schemas match design (if applicable)
|
||||
- [ ] API endpoints match spec (if applicable)
|
||||
- [ ] No TODO/FIXME comments or placeholder code
|
||||
- [ ] Required environment variables documented
|
||||
- [ ] No hardcoded secrets or credentials
|
||||
- [ ] Code follows existing codebase patterns
|
||||
|
||||
### Test Validation (if defined)
|
||||
| Test Type | Passed | Failed | Coverage |
|
||||
|-----------|--------|--------|----------|
|
||||
| Unit | X | X | X% |
|
||||
```
|
||||
|
||||
#### Report:
|
||||
|
||||
```markdown
|
||||
## Verification Results
|
||||
| Check | Status | Notes |
|
||||
|-------|--------|-------|
|
||||
| Files | Pass/Warn/Fail | [Details] |
|
||||
|
||||
**Issues Found:** [List or "None"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### STEP 3: Implementation Summary
|
||||
|
||||
`🧹 [FINALIZATION STEP 3: Implementation Summary]`
|
||||
|
||||
**Objective:** Create comprehensive summary of what was built.
|
||||
|
||||
```markdown
|
||||
## Implementation Summary
|
||||
**Feature:** [Name] | **Completed:** [Date] | **Completion:** [X]%
|
||||
|
||||
### What Was Built
|
||||
[2-4 sentences]
|
||||
|
||||
### Files Created
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `path/file` | [Description] |
|
||||
|
||||
### Files Modified
|
||||
| File | Changes |
|
||||
|------|---------|
|
||||
| `path/file` | [Description] |
|
||||
|
||||
### Dependencies Added
|
||||
| Package | Version | Purpose |
|
||||
|---------|---------|---------|
|
||||
|
||||
### Configuration Required
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
|
||||
### Known Limitations / Blocked Items
|
||||
[List or "None"]
|
||||
```
|
||||
|
||||
Add this summary to `overview.md` under `## Completion Summary`.
|
||||
|
||||
---
|
||||
|
||||
### STEP 4: Documentation Review
|
||||
|
||||
`🧹 [FINALIZATION STEP 4: Documentation Review]`
|
||||
|
||||
**Objective:** Identify documentation needing updates — additions for the feature AND corrections to stale/wrong/missing entries it exposed.
|
||||
|
||||
| Document | Check For | Action |
|
||||
|----------|-----------|--------|
|
||||
| `AGENTS.md` + `.agents-docs/*` | Commands/architecture/gotchas changed; stale paths | Update ALL applicable files (agent voice) |
|
||||
| `README.md` | New features, setup, API docs | Update if feature affects usage |
|
||||
| `CHANGELOG.md` | Version history | Add entry for feature |
|
||||
| `.env.example` | Environment variables | Add new required vars |
|
||||
| `API.md` / human docs | API documentation | Update with new endpoints |
|
||||
| `CLAUDE.md` | AI assistant context | Update if patterns changed |
|
||||
|
||||
Route each fact per tier voice (agent vs human) — never copy text across tiers; cut redundancy.
|
||||
|
||||
Report: table of documents needing updates with proposed changes. List each document with specific additions.
|
||||
|
||||
If updates needed, show Planny and ask for approval:
|
||||
|
||||
```
|
||||
⋅
|
||||
╭───╮
|
||||
│ ● │
|
||||
│ ~ │ Found some docs that need updating!
|
||||
╰───╯
|
||||
```
|
||||
|
||||
> Reply "approve" to proceed with doc updates, or specify which to skip.
|
||||
|
||||
Do NOT make documentation changes without user approval.
|
||||
|
||||
---
|
||||
|
||||
### STEP 5: User Feedback (Optional)
|
||||
|
||||
`🧹 [FINALIZATION STEP 5: User Feedback]`
|
||||
|
||||
**Objective:** Collect optional feedback before archival.
|
||||
|
||||
Ask the user: "Would you like to provide feedback on this run? (optional)" If no, skip to Step 6.
|
||||
|
||||
If yes, collect:
|
||||
1. **Rating** (1-10): "How would you rate this workflow run overall?"
|
||||
2. **Reason**: "Brief reason for your rating?"
|
||||
3. **Went Well**: "What went well?"
|
||||
4. **Went Poorly**: "What went poorly or could improve?"
|
||||
|
||||
Append to `overview.md` (in the active spec directory):
|
||||
|
||||
```markdown
|
||||
## User Feedback
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Rating | [1-10] |
|
||||
| Reason | [response] |
|
||||
| Went Well | [response] |
|
||||
| Went Poorly | [response] |
|
||||
```
|
||||
|
||||
Ask: "Submit this feedback + run metrics to the maintainer via GitHub? (optional)" Hold as "submission consent". If declined, skip to Step 6.
|
||||
|
||||
---
|
||||
|
||||
### STEP 6: Spec Cleanup
|
||||
|
||||
`🧹 [FINALIZATION STEP 6: Spec Cleanup]`
|
||||
|
||||
**Objective:** Archive completed specifications.
|
||||
|
||||
**Confirm with user before moving files.**
|
||||
|
||||
1. Create: `specs--completed/<feature-name>/`
|
||||
2. Move all contents of `specs/<feature-name>/`:
|
||||
- `overview.md` (with completion summary)
|
||||
- All `phase-X.md` files
|
||||
- `PLAN-DRAFT.md`, `PLAN-CONVERSATION-*.md`, `pathfinder/` (if present)
|
||||
3. Remove temporary scratch files not part of the final spec record
|
||||
4. Verify original directory empty and can be removed
|
||||
|
||||
**Keep folder name exactly as-is during archival.**
|
||||
|
||||
---
|
||||
|
||||
### STEP 6.5: Community Feedback Submission
|
||||
|
||||
`🧹 [FINALIZATION STEP 6.5: Community Feedback Submission]`
|
||||
|
||||
If Step 5 feedback/consent was declined, skip to Step 7. Otherwise assemble/preview/submit the payload:
|
||||
|
||||
Read references/community-feedback-submission.md
|
||||
|
||||
---
|
||||
|
||||
### STEP 7: Final Confirmation
|
||||
|
||||
`🧹 [FINALIZATION STEP 7: Final Confirmation]`
|
||||
|
||||
**Objective:** Confirm all finalization steps complete.
|
||||
|
||||
```markdown
|
||||
## Finalization Complete
|
||||
|
||||
### Summary
|
||||
- **Feature:** [Name]
|
||||
- **Status:** Complete
|
||||
- **Completion Rate:** [X]% ([Y]/[Z] tasks)
|
||||
- **Archived To:** `specs--completed/<feature-name>/`
|
||||
|
||||
<!-- METRICS_JSON {"step": "finalize", "completion_rate_at_audit": 0.95, "tasks_completed": 19, "tasks_total": 20, "verification_failures_found": 1, "documentation_updates_needed": 2} -->
|
||||
|
||||
Replace METRICS_JSON values with actuals. `completion_rate_at_audit` = Y/Z as decimal (e.g., 19/20 = 0.95).
|
||||
|
||||
### Finalization Steps Completed
|
||||
- [x] Step 1: Task Completion Audit
|
||||
- [x] Step 2: Implementation Verification
|
||||
- [x] Step 3: Implementation Summary
|
||||
- [x] Step 4: Documentation Review
|
||||
- [x] Step 5: User Feedback (Optional)
|
||||
- [x] Step 6: Spec Cleanup
|
||||
- [x] Step 6.5: Community Feedback Submission
|
||||
- [x] Step 7: Final Confirmation
|
||||
|
||||
### Files Created/Modified During Finalization
|
||||
- `specs/<feature-name>/overview.md` - Added completion summary
|
||||
- `README.md` - [if updated]
|
||||
- `CHANGELOG.md` - [if updated]
|
||||
|
||||
### Archived Files
|
||||
[List all files moved to specs--completed/<feature-name>/]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
```
|
||||
⋅
|
||||
╭───╮
|
||||
│ ★ │
|
||||
│ ◡ │ You did it! Feature complete!
|
||||
╰───╯
|
||||
```
|
||||
|
||||
> IMPLEMENTATION COMPLETED!
|
||||
> All tasks finished.
|
||||
> Specs archived to `specs--completed/<feature-name>/`.
|
||||
> Thank you for using the Plan2Code workflow!
|
||||
|
||||
### Handling Incomplete Implementations
|
||||
|
||||
| Completion | Action |
|
||||
|-----------|--------|
|
||||
| **>75%** | Finalize with notice. List incomplete items. Note remaining tasks for follow-up cycle. |
|
||||
| **<75%** | Recommend returning to implementation. List incomplete phases with task counts. Options: 1) Return via `/plan2code-3-implement` 2) Proceed with partial finalization. |
|
||||
|
||||
## Abort Handling
|
||||
|
||||
If user says "abort", "cancel", or similar:
|
||||
1. Confirm: "Abort finalization? Implementation remains but won't be validated or archived."
|
||||
2. If confirmed: Note progress, explain spec files remain in place
|
||||
3. Stop finalization
|
||||
|
||||
## Recovery
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Incomplete tasks | User chooses: complete, partial, or abandon |
|
||||
| Missing spec files | Ask for all phase-X.md files |
|
||||
| Doc updates rejected | Skip updates, note in summary |
|
||||
|
||||
## Learning Capture
|
||||
|
||||
At session end, if you discovered undocumented commands, dependency quirks, gotchas (>5min cost), framework workarounds, or missing `AGENTS.md` patterns → prompt user to update AGENTS.md. If yes, apply the edit directly.
|
||||
|
||||
## Session End
|
||||
|
||||
(Step 7 already delivered the completion summary — don't repeat it.)
|
||||
|
||||
Suggested commit (only if README, CHANGELOG, or other tracked docs were updated):
|
||||
```
|
||||
git commit -m "chore: finalize and archive <feature-name>" -m "<JIRA-Ticket-ID>" -m "AI Assisted"
|
||||
```
|
||||
|
||||
Returning context: Feature complete. Specs archived to `specs--completed/<feature-name>/`.
|
||||
@@ -0,0 +1,72 @@
|
||||
# Community Feedback Submission (STEP 6.5 detail)
|
||||
|
||||
> Loaded by `src/plan2code-4-finalize.md` STEP 6.5. This file has no character limit (see `AGENTS-architecture.md` Reference Files).
|
||||
|
||||
## 1. Generate a fresh `run_id`
|
||||
|
||||
Compute your own current timestamp and a freshly generated random 4-character hex string — do not reuse the example value shown below or anywhere in this spec. Format: `run-<YYYYMMDD>-<HHMMSS>-<4-hex-chars>` (e.g. `run-20260715-143000-a1b2`).
|
||||
|
||||
## 2. Assemble the payload
|
||||
|
||||
Read `PLAN-DRAFT-*.md`, `phase-*.md`, and `overview.md` in `specs--completed/<feature-name>/` (STEP 6 has already archived them there) and reason over their content to gather:
|
||||
|
||||
- `step1`: `final_confidence`, `confidence_breakdown` (`{requirements, feasibility, integration, risk}`), `clarification_rounds`, `tech_stack_revision_rounds`, `verification_gaps_found`, `functional_requirements_count`, `non_functional_requirements_count`, `risk_count`, `phase_count`
|
||||
- `step2`: `total_tasks`, `phase_count`, `parallel_groups_identified`, `requirement_coverage_percent`, `verification_items_added`
|
||||
- `step3`: `task_completion_rate`, `tasks_completed`, `tasks_total`, `blocker_count`
|
||||
- `step4`: `completion_rate_at_audit`, `verification_failures_found`, `documentation_updates_needed`, `archival_succeeded` (safe to read now that Step 6 has run)
|
||||
- `plan2code_version` — from `version.json`
|
||||
- `prompt_versions_short` — first 12 characters of each of the 8 prompt file names' content (`plan`, `revise_plan`, `document`, `implement`, `finalize`, `init`, `init_update`, `quick_task`). You do not have `sha256File()` available — note these as best-effort/approximate if you cannot compute a real hash, or omit the field entirely if you cannot.
|
||||
|
||||
**Never include** `project.name` or any bulky arrays (e.g. `tasks_per_phase`).
|
||||
|
||||
Include the feedback collected at Step 5 as `user_feedback`: `overall_rating`, `rating_reason`, `what_went_well`, `what_went_poorly`.
|
||||
|
||||
Assemble the full nested JSON object matching this schema exactly:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "1.0",
|
||||
"run_id": "run-<YYYYMMDD>-<HHMMSS>-<4-hex>",
|
||||
"plan2code_version": "<from version.json>",
|
||||
"prompt_versions_short": { "plan": "...", "revise_plan": "...", "document": "...", "implement": "...", "finalize": "...", "init": "...", "init_update": "...", "quick_task": "..." },
|
||||
"step1": { "final_confidence": 0, "confidence_breakdown": { "requirements": 0, "feasibility": 0, "integration": 0, "risk": 0 }, "clarification_rounds": 0, "tech_stack_revision_rounds": 0, "verification_gaps_found": 0, "functional_requirements_count": 0, "non_functional_requirements_count": 0, "risk_count": 0, "phase_count": 0 },
|
||||
"step2": { "total_tasks": 0, "phase_count": 0, "parallel_groups_identified": 0, "requirement_coverage_percent": 0, "verification_items_added": 0 },
|
||||
"step3": { "task_completion_rate": 0, "tasks_completed": 0, "tasks_total": 0, "blocker_count": 0 },
|
||||
"step4": { "completion_rate_at_audit": 0, "verification_failures_found": 0, "documentation_updates_needed": 0, "archival_succeeded": true },
|
||||
"user_feedback": { "overall_rating": 0, "rating_reason": "...", "what_went_well": "...", "what_went_poorly": "..." }
|
||||
}
|
||||
```
|
||||
|
||||
## 3. Render the GitHub Issue
|
||||
|
||||
- **Title:** `` `[Feedback] v<plan2code_version> — rating <N>/10` `` (e.g. `[Feedback] v1.15.3 — rating 8/10`)
|
||||
- **Body:** a short human-readable markdown summary (version, rating, headline numbers such as completion rate and confidence), followed by the full payload as `<!-- METRICS_JSON {...} -->` (same HTML-comment convention used in Step 7's own summary block)
|
||||
- **Label:** `community-feedback`
|
||||
|
||||
Estimate the combined URL-encoded size of `title` + `body` + `labels`. If it exceeds roughly 8KB, warn the user and offer to truncate the longest free-text `user_feedback` field(s) — starting with `rating_reason`, then `what_went_well`/`what_went_poorly` — before proceeding. This size limit only affects the browser/print fallback tiers (below), not the `gh` CLI tier.
|
||||
|
||||
## 4. Preview and approval gate
|
||||
|
||||
Display the exact rendered title, full body (including the `METRICS_JSON` block), and label(s) to the user, mirroring the Step 4 Documentation Review pattern:
|
||||
|
||||
```
|
||||
⋅
|
||||
╭───╮
|
||||
│ ● │
|
||||
│ ~ │ Ready to submit your feedback to the maintainer!
|
||||
╰───╯
|
||||
```
|
||||
|
||||
> Reply "approve" to proceed with submission, or "skip" to cancel.
|
||||
|
||||
Do NOT proceed to submission without an explicit "approve" reply. A "skip" or any non-approval reply cancels this sub-step entirely and proceeds to Step 7 with no submission.
|
||||
|
||||
## 5. Tiered submission
|
||||
|
||||
On approval, attempt each tier in order until one succeeds:
|
||||
|
||||
1. **Tier 1 (primary):** Attempt `gh issue create --repo jparkerweb/plan2code --title "<title>" --body "<body>" --label community-feedback` via your shell tool. If it succeeds, report the created issue URL to the user and stop.
|
||||
2. **Tier 2 (secondary):** If `gh` is not installed or not authenticated (command fails), construct the URL `https://github.com/jparkerweb/plan2code/issues/new?title=<url-encoded title>&body=<url-encoded body>&labels=community-feedback` and attempt to open it in the user's default browser using the OS-appropriate command (`start "<url>"` on Windows, `open "<url>"` on macOS, `xdg-open "<url>"` on Linux). Tell the user they still need to click "Submit issue" themselves since they must be logged in.
|
||||
3. **Tier 3 (tertiary):** If no browser can be opened (e.g. no shell tool access, headless/remote session), print the same URL from Tier 2 to the terminal/chat: "Please open this URL in your browser and click 'Submit issue' to share your feedback: `<url>`".
|
||||
|
||||
After any tier succeeds (or the user manually confirms Tier 3 submission), proceed to Step 7 as normal.
|
||||
Reference in New Issue
Block a user