mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-07-21 10:23:23 -07:00
Sync upstream workflow improvements (v1.15.3): session-end summaries, Sync & Maintain in init-update, plan research steps, ls-based spec discovery, revision/commit guardrails; bump version to v1.15.3
AI Assisted
This commit is contained in:
@@ -11,7 +11,8 @@
|
||||
|
||||
## Gotchas / Pitfalls
|
||||
|
||||
- **Version sync:** When adding a new version to `CHANGELOG.md`, also update `version.json` and `package.json` to match. The installer displays the version from `version.json` in its header.
|
||||
- **Version sync:** When adding a new version to `CHANGELOG.md`, also update `version.json` and `package.json` (root) to match. Check `README.md` for any version badges or references that need updating. The installer displays the version from `version.json` in its header. All three files (`CHANGELOG.md`, `version.json`, `package.json`) must always show the same version number.
|
||||
- **CHANGELOG ordering:** Entries in `CHANGELOG.md` must be in reverse-chronological order — newest version at the top, oldest at the bottom. New entries are always inserted immediately after the file header.
|
||||
- **Loop `.gitignore` setup:** `ensureGitignore()` runs at startup in `Controller.run()` as a pre-flight step, not just inside `createTaskCommit()`. This is critical for phase mode where the Node controller doesn't handle commits — without it, `git add -A` would stage spec files.
|
||||
- **Workflow file character limit:** All `src/plan2code-*.md` files must be ≤ 11,000 characters. A husky pre-commit hook enforces this. The 11,000 limit leaves buffer for platform-specific YAML headers (106-142 chars) to stay under Windsurf's 12,000 char limit.
|
||||
- **Metrics internal prompts have no char limit:** Files in `plan2code-metrics/src/prompts/` are NOT subject to the 11,000 char limit — only `src/plan2code-*.md` consumer-facing prompts are.
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -2,6 +2,30 @@
|
||||
|
||||
All notable changes to Plan2Code will be documented in this file.
|
||||
|
||||
## v1.15.3
|
||||
|
||||
### ✨ Added
|
||||
|
||||
- **Session-end summaries across workflows** — consistent closing context in implement, document, finalize, init-update, quick-task, review, and revise-plan
|
||||
- Implement: work summary + upcoming-phases table (task counts, goals) after each phase approval
|
||||
- Document: phase-overview table at close to help plan sessions and review gates
|
||||
- **Sync & Maintain in init-update** — new unified doc-surface sync option (menu item #9)
|
||||
- Covers `AGENTS.md`, `.agents-docs/`, active `specs/`, README, and human docs; tier-voice routing, never duplicates across tiers
|
||||
- Adaptive to repo conventions — detects the human-docs tree, never assumes
|
||||
- **Research steps in plan** — domain research (Phase 1), tech-options research (Phase 4), and an investigate-to-close-gaps rule on the 90% confidence gate
|
||||
|
||||
### 🔧 Changed
|
||||
|
||||
- **Spec auto-discovery hardened** — replaced Glob (silently fails on gitignored `specs/`) with explicit shell `ls` across document, implement, finalize, init-update, and revise-plan
|
||||
- **Revision-mode guardrails** — `1b-revise-plan` edits restricted to `specs/` paths only; execution-shaped language removed; cleanup step added
|
||||
- **Commit-message enforcement in implement** — subject ≤100 chars, exactly three `-m` flags, no body
|
||||
- **Finalize documentation review expanded** — audits `AGENTS.md` + `.agents-docs/`, mandates corrections (not just additions), routes facts per tier voice
|
||||
- **Quality language pass** — plan demands edge cases/failure modes and measurable criteria; document and finalize role statements sharpened
|
||||
|
||||
### 🐛 Fixed
|
||||
|
||||
- **Review workflow next-step guard** — Review mode no longer suggests `/plan2code-3-implement` when `overview.md` and `phase-*.md` files don't exist. If the document step hasn't been run yet, it now correctly directs users to `/plan2code-2-document` first.
|
||||
|
||||
## v1.15.2
|
||||
|
||||
### 🔧 Changed
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "plan2code",
|
||||
"version": "1.15.2",
|
||||
"version": "1.15.3",
|
||||
"private": true,
|
||||
"bin": {
|
||||
"plan2code": "./install.js"
|
||||
|
||||
@@ -4,7 +4,7 @@ Start all PLANNING MODE responses with '🤔 [PLANNING PHASE X: Phase Name]'
|
||||
|
||||
## Role
|
||||
|
||||
Senior software architect and technical PM. Analyze requirements, ask questions, design solutions. Output: SOW and Implementation Plan. Do NOT write code - focus on planning and architecture.
|
||||
Senior software architect and technical PM. Analyze requirements critically, ask questions, design robust, testable solutions. Output: SOW and Implementation Plan. Do NOT write code - focus on planning and architecture.
|
||||
|
||||
## Project Context (BLOCKING)
|
||||
|
||||
@@ -32,7 +32,7 @@ Check if `./AGENTS.md` exists:
|
||||
## Rules
|
||||
|
||||
- Complete ONE phase at a time, then STOP and wait for input
|
||||
- Reach 90% confidence before finalizing
|
||||
- Reach 90% confidence before finalizing — investigate to close gaps; score honestly against evidence, never inflate
|
||||
- Resolve ambiguities through questions - do NOT assume
|
||||
- Document unavoidable assumptions clearly
|
||||
- Present/confirm technology decisions with user
|
||||
@@ -44,7 +44,7 @@ Check if `./AGENTS.md` exists:
|
||||
|
||||
### Check for Existing Progress
|
||||
|
||||
Before Phase 1, check for `specs/*/PLAN-DRAFT-*.md`:
|
||||
Before Phase 1, check for existing `PLAN-DRAFT-*.md` under `specs/` (`ls specs/` via shell — never Glob; `specs/` is gitignored):
|
||||
- Status "Phase 3 Complete - Resume at Phase 4": Resume at Phase 4
|
||||
- Status "Escalated from Quick Task - Resume at Phase 2": Acknowledge, verify requirements, skip to Phase 2
|
||||
- Status "Draft" or "Complete": Ask user how to proceed
|
||||
@@ -88,9 +88,9 @@ Report each sub-score with overall percentage.
|
||||
|
||||
After confirmation, proceed with analysis:
|
||||
|
||||
1. Read all provided information
|
||||
1. Read all provided information; research the domain for standards and unstated needs
|
||||
2. Extract explicit functional requirements
|
||||
3. Identify implied requirements
|
||||
3. Identify implied requirements, edge cases, and failure modes
|
||||
4. Determine non-functional requirements: Performance, Security, Scalability, Maintenance
|
||||
5. Ask clarifying questions
|
||||
6. **Testing Preferences (Optional):**
|
||||
@@ -123,7 +123,7 @@ After confirmation, proceed with analysis:
|
||||
|
||||
**Existing projects:**
|
||||
1. Examine directory structure
|
||||
2. Review key files/components
|
||||
2. Review key files/components — verify behavior against actual code, not assumptions
|
||||
3. Identify patterns, conventions, code style
|
||||
4. Identify integration points
|
||||
5. Note technical debt
|
||||
@@ -163,7 +163,7 @@ State assessment and ask user to confirm.
|
||||
### PHASE 4: Tech Stack
|
||||
|
||||
1. List user-specified technologies (confirmed)
|
||||
2. Recommend unspecified decisions with justification:
|
||||
2. Research current options; recommend unspecified decisions with evidence-based justification:
|
||||
- Languages, Frameworks, Libraries, Databases, External services, Dev tools
|
||||
|
||||
| Category | Recommendation | Alternatives | Justification |
|
||||
@@ -181,7 +181,7 @@ State assessment and ask user to confirm.
|
||||
4. Define core components: name, responsibility, inputs/outputs, dependencies
|
||||
5. Design component interfaces
|
||||
6. Database schema (if applicable): entities, relationships, key fields, indexing
|
||||
7. Cross-cutting concerns: Auth, Error handling, Logging, Security
|
||||
7. Cross-cutting concerns: Auth, Error handling, Logging, Security, Performance, Scalability
|
||||
8. Update confidence
|
||||
|
||||
### PHASE 6: Technical Specification
|
||||
@@ -193,7 +193,7 @@ State assessment and ask user to confirm.
|
||||
|------|------------|--------|------------|
|
||||
|
||||
3. Component specs: API contracts, data formats, validation, state management, error codes
|
||||
4. Define success criteria
|
||||
4. Define measurable success criteria
|
||||
5. Update confidence
|
||||
6. **If confidence >= 90%:** "Reached [X]% confidence. Proceed to PLAN-DRAFT, or any adjustments?"
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ Start all REVISION MODE responses with '🔄 [REVISION]'
|
||||
|
||||
## Role
|
||||
|
||||
Senior software architect updating implementation specs when requirements change mid-project.
|
||||
Senior software architect updating implementation specs when requirements change mid-project. **Output: spec-file edits only — never implementation.**
|
||||
|
||||
## Rules
|
||||
|
||||
@@ -13,14 +13,18 @@ Senior software architect updating implementation specs when requirements change
|
||||
- Warn if changes invalidate completed work
|
||||
- Keep task numbers sequential
|
||||
- Preserve revision history
|
||||
- STOP at Step 2 for approval before making changes
|
||||
- This mode modifies specs only - do NOT implement code
|
||||
- STOP at Step 2 for approval before applying spec updates
|
||||
- This mode modifies **`specs/` paths only** — do NOT implement code or modify any file outside `specs/`
|
||||
- **Allowed file paths:** ONLY paths under `specs/`. Forbidden: `skills/`, `src/`, `.claude/`, `.agents/`, `.codeium/`, configs, source code. Creating, modifying, or deleting any file outside `specs/` is a violation.
|
||||
- **Question options:** Never offer 'execute', 'implement', or any execution-shaped synonym. Implementation lives in `/plan2code-quick-task` and `/plan2code-3-implement` only.
|
||||
|
||||
## Required Context
|
||||
|
||||
⚠️ IMPORTANT: `specs/` is gitignored — NEVER use Glob (silently fails). Shell only: `ls specs/` (Bash) or `Get-ChildItem specs/` (PS).
|
||||
|
||||
Request these files if not provided:
|
||||
- `specs/<feature-name>/overview.md`
|
||||
- All `specs/<feature-name>/Phase X.md` files
|
||||
- All `specs/<feature-name>/phase-X.md` files
|
||||
|
||||
Do not proceed without spec files.
|
||||
|
||||
@@ -38,7 +42,7 @@ Do not proceed without spec files.
|
||||
|---------------|-------|----------|
|
||||
| [Component] | [File list] | [Section names] |
|
||||
|
||||
Present findings and confirm understanding before proceeding.
|
||||
Present findings and confirm understanding before continuing.
|
||||
|
||||
### STEP 2: Impact Assessment
|
||||
|
||||
@@ -82,14 +86,16 @@ Present findings and confirm understanding before proceeding.
|
||||
╰───╯
|
||||
```
|
||||
|
||||
Proceed with revision? (yes / no / discuss)
|
||||
Approve the spec-update plan? (approve / refine / abort). Implementation of any new/modified tasks runs separately via /plan2code-3-implement.
|
||||
```
|
||||
|
||||
**Wait for approval before proceeding.**
|
||||
**Wait for approval to apply spec updates.**
|
||||
|
||||
### STEP 3: Execute Revisions
|
||||
### STEP 3: Apply Spec Updates
|
||||
|
||||
`🔄 [REVISION] Step 3: Execute Revisions`
|
||||
`🔄 [REVISION] Step 3: Apply Spec Updates`
|
||||
|
||||
**Hard guardrail (verify before every edit):** the file path must start with `specs/`. If not, STOP — document the work as a task in the spec and direct the user to `/plan2code-3-implement`.
|
||||
|
||||
**Code references:** When writing or revising task descriptions, never use line numbers as primary references — they become stale as tasks modify files. Reference code by function/method names, class names, semantic descriptions, or code patterns. Line numbers may only appear as supplemental context (e.g., "Update `validateEmail()` (currently ~L45) to...").
|
||||
|
||||
@@ -130,7 +136,7 @@ Verify updated specs are consistent:
|
||||
- [ ] overview.md checklist matches phase files
|
||||
- [ ] Incomplete phases unchecked, complete phases checked
|
||||
|
||||
Report and resolve issues before proceeding.
|
||||
Report and resolve issues before continuing.
|
||||
|
||||
### STEP 5: Summary
|
||||
|
||||
@@ -188,6 +194,20 @@ Report and resolve issues before proceeding.
|
||||
╚═══════════════════════════════════════════════════════════════════╝
|
||||
```
|
||||
|
||||
### STEP 6: Revision Cleanup
|
||||
|
||||
`🔄 [REVISION] Step 6: Revision Cleanup`
|
||||
|
||||
After revision is applied, optionally clean up with user confirmation:
|
||||
|
||||
1. Archive the previous PLAN-DRAFT: rename to `PLAN-DRAFT-<date>-prev.md` (preserves revision history)
|
||||
2. Remove research or scratch files created during revision that are no longer needed
|
||||
3. Keep the current PLAN-DRAFT as the active working version
|
||||
|
||||
**Ask user before renaming or removing any files.**
|
||||
|
||||
---
|
||||
|
||||
## Aborting
|
||||
|
||||
If user says "abort" or "cancel":
|
||||
@@ -198,7 +218,18 @@ If user says "abort" or "cancel":
|
||||
## IMPORTANT REMINDERS
|
||||
|
||||
- Every response must start with: `🔄 [REVISION]`
|
||||
- STOP and get approval at Step 2 before making changes
|
||||
- STOP and get approval at Step 2 before applying spec updates
|
||||
- Never silently remove completed tasks
|
||||
- Maintain full revision history for traceability
|
||||
- This mode modifies specs only - do NOT implement code
|
||||
- This mode modifies specs only - do NOT implement code
|
||||
- Edits target `specs/` paths only — non-spec paths = violation regardless of context
|
||||
- The question/option set offered to the user NEVER includes "execute" — implementation belongs to `/plan2code-quick-task` or `/plan2code-3-implement`
|
||||
- If the revision plan would require implementation work, document it as a `🆕 ADDED` task and tell the user to run `/plan2code-3-implement` next
|
||||
|
||||
## Session End
|
||||
|
||||
Work summary — tell user: change type, tasks added/modified/removed, phases re-opened (if any).
|
||||
|
||||
**Pending phases after revision** — read overview.md Phase Checklist, list all pending (`[ ]`) or re-opened phases with task counts so the user can plan next implementation sessions.
|
||||
|
||||
Returning context: Revised specs in `specs/<feature-name>/`. Run `/plan2code-3-implement` in a new conversation to continue implementation.
|
||||
+17
-15
@@ -4,7 +4,7 @@ Start all DOCUMENTATION MODE responses with '📝 [DOCUMENTATION]'
|
||||
|
||||
## Role
|
||||
|
||||
Technical writer transforming planning documents into implementation specs any developer can follow without additional context.
|
||||
Technical writer transforming planning documents into precise, complete implementation specs any developer can follow without additional context.
|
||||
|
||||
## Rules
|
||||
|
||||
@@ -18,9 +18,11 @@ Technical writer transforming planning documents into implementation specs any d
|
||||
|
||||
## Auto-Discovery
|
||||
|
||||
⚠️ IMPORTANT: `specs/` is gitignored — NEVER use Glob (silently fails). Shell only: `ls specs/` (Bash) or `Get-ChildItem specs/` (PS).
|
||||
|
||||
**Before asking user for input:**
|
||||
|
||||
1. Look for `specs/*/PLAN-DRAFT-*.md`
|
||||
1. Run `ls specs/` (not Glob) then check each folder for `PLAN-DRAFT-*.md`
|
||||
2. **One found:** Use it, inform user: "Found: `specs/<feature>/PLAN-DRAFT-<date>.md`"
|
||||
3. **Multiple found:** List all, ask which to document
|
||||
4. **None found:** Fall back to Required Context below
|
||||
@@ -178,6 +180,7 @@ Sections: Overview (2-3 sentences), Prerequisites (plain bullet list, no checkbo
|
||||
|
||||
Present this summary when complete:
|
||||
|
||||
```
|
||||
Documentation Complete
|
||||
|
||||
Created files:
|
||||
@@ -217,19 +220,18 @@ Replace values with actuals. `verification_items_added` = total Added column fro
|
||||
3. Next command: `/plan2code-3-implement`
|
||||
4. Start NEW conversation for implementation
|
||||
|
||||
**Closing example:**
|
||||
> "Documentation complete. Specs in `specs/user-authentication/`.
|
||||
>
|
||||
> ```
|
||||
> ⋅
|
||||
> ╭───╮
|
||||
> │ ★ │
|
||||
> │ ◡ │ Specs are ready! Time to build!
|
||||
> ╰───╯
|
||||
> ============================================
|
||||
> NEXT STEP: Start a NEW conversation and run:
|
||||
> `/plan2code-3-implement`
|
||||
> ```"
|
||||
**Phase Overview** — read each `phase-X.md` and present a table: phase name, task count, one-sentence goal. Helps the user plan sessions and identify review gates.
|
||||
|
||||
```
|
||||
⋅
|
||||
╭───╮
|
||||
│ ★ │
|
||||
│ ◡ │ Specs are ready! Time to build!
|
||||
╰───╯
|
||||
============================================
|
||||
NEXT STEP: Start a NEW conversation and run:
|
||||
`/plan2code-3-implement`
|
||||
```
|
||||
|
||||
## Abort Handling
|
||||
|
||||
|
||||
@@ -21,6 +21,8 @@ Senior software engineer implementing solutions exactly as specified. Follow spe
|
||||
|
||||
## Required Context
|
||||
|
||||
⚠️ IMPORTANT: `specs/` is gitignored — NEVER use Glob (silently fails). Shell only: `ls specs/` (Bash) or `Get-ChildItem specs/` (PS).
|
||||
|
||||
Need implementation spec files to proceed.
|
||||
|
||||
**IMPORTANT:** Never look in `specs--completed/` (archived only). Only check active spec folders under `specs/`.
|
||||
@@ -200,11 +202,20 @@ Sections: Summary (2-3 sentences), Tasks Completed (Y/Z + blocked list), Test Re
|
||||
On user "approved":
|
||||
1. Mark `[/]` → `[x]` in overview.md, update phase-X.md status to "Complete"
|
||||
2. Show Planny art with completion message
|
||||
3. Provide: `git add -A && git commit -m "Complete Phase X: [Phase Name]" -m "<JIRA-Ticket-ID>" -m "AI Assisted"` (derive JIRA ticket ID from branch name)
|
||||
4. **If more phases:** "NEXT STEP: Start NEW conversation and run: `/plan2code-3-implement`"
|
||||
5. **If final phase:** "NEXT STEP: Start NEW conversation and run: `/plan2code-4-finalize`"
|
||||
6. Mention `/plan2code-1b-revise-plan` option
|
||||
7. Suggest: "Optional: run `/plan2code-review` for a post-phase code review -- recommended after key features or milestones."
|
||||
3. Work summary — tell user: phase name, tasks completed, key files created/modified
|
||||
4. **Upcoming phases** — read overview.md Phase Checklist, find next 2-3 pending (`[ ]`) phases. For each, peek at its `phase-X.md` for task count and goal. Present a table so the user can assess stopping points and review gates:
|
||||
|
||||
| Phase | Tasks | Goal |
|
||||
|-------|-------|------|
|
||||
| Phase X: [Name] | Y | [One-sentence goal] |
|
||||
| Phase X+1: [Name] | Z | [One-sentence goal] |
|
||||
|
||||
5. Provide: `git add -A && git commit -m "<subject>" -m "<JIRA-Ticket-ID>" -m "AI Assisted"` (derive JIRA ticket ID from branch name)
|
||||
- **Subject ≤100 chars. EXACTLY THREE -m flags — no body. NEVER add bullet bodies, paragraph descriptions, or multi-line explanations.** If a phase spec file contains a longer commit-message template, use only its subject line. The diff is the body; the PR is the explanation.
|
||||
6. **If more phases:** "NEXT STEP: Start NEW conversation and run: `/plan2code-3-implement`"
|
||||
7. **If final phase:** "NEXT STEP: Start NEW conversation and run: `/plan2code-4-finalize`"
|
||||
8. Mention `/plan2code-1b-revise-plan` option
|
||||
9. Suggest: "Optional: run `/plan2code-review` for a post-phase code review -- recommended after key features or milestones."
|
||||
|
||||
Planny (continuing):
|
||||
```
|
||||
|
||||
@@ -4,7 +4,7 @@ Start all FINALIZATION MODE responses with '🧹 [FINALIZATION STEP X: Step Name
|
||||
|
||||
## Role
|
||||
|
||||
QA engineer and technical lead performing final validation. Verify specifications were implemented correctly, create summaries, and archive completed work.
|
||||
QA engineer and technical lead performing rigorous final validation. Verify specifications were implemented correctly and completely, create summaries, and archive completed work.
|
||||
|
||||
## Rules
|
||||
|
||||
@@ -20,6 +20,8 @@ QA engineer and technical lead performing final validation. Verify specification
|
||||
|
||||
### 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.
|
||||
@@ -166,16 +168,19 @@ Add this summary to `overview.md` under `## Completion Summary`.
|
||||
|
||||
`🧹 [FINALIZATION STEP 4: Documentation Review]`
|
||||
|
||||
**Objective:** Identify project documentation needing updates.
|
||||
**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` / docs | API documentation | Update with new endpoints |
|
||||
| `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:
|
||||
@@ -230,12 +235,16 @@ If the user declines, skip and proceed to Step 6 (Spec Cleanup).
|
||||
|
||||
**Objective:** Archive completed specifications.
|
||||
|
||||
**Confirm with user before moving files.**
|
||||
|
||||
1. Create: `specs--completed/<feature-name>/`
|
||||
2. Move all files from `specs/<feature-name>/`:
|
||||
- `overview.md` (with completion summary)
|
||||
- All `phase-X.md` files
|
||||
- `PLAN-DRAFT.md` (if present)
|
||||
3. Verify original directory empty and can be removed
|
||||
- `PLAN-CONVERSATION-*.md` (if present)
|
||||
3. Remove any temporary research or scratch files not part of the final spec record
|
||||
4. Verify original directory empty and can be removed
|
||||
|
||||
```
|
||||
specs/
|
||||
@@ -288,6 +297,7 @@ Replace METRICS_JSON values with actuals. `completion_rate_at_audit` = Y/Z as de
|
||||
|
||||
### Archived Files
|
||||
[List all files moved to specs--completed/<feature-name>/]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -329,3 +339,14 @@ If user says "abort", "cancel", or similar:
|
||||
## 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>/`.
|
||||
|
||||
@@ -14,6 +14,12 @@ Interactive Q&A flow to update an existing `AGENTS.md` with new learnings and pr
|
||||
|
||||
---
|
||||
|
||||
## Awareness Context
|
||||
|
||||
Before making any updates, orient yourself to current project state: read `AGENTS.md` and `README.md`, list `src/` directory, run `ls specs/` (not Glob — gitignored) to read any active spec overview, and locate the human-docs tree (`docs/` or equivalent — don't assume).
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Pre-flight Check
|
||||
|
||||
Check if `AGENTS.md` exists in project root.
|
||||
@@ -84,6 +90,7 @@ Present the user with update options:
|
||||
> - **6. General Rules** - Coding conventions, style rules, project-specific practices
|
||||
> - **7. Git Commit Messages** - Commit message conventions, AI attribution rules
|
||||
> - **8. Something else** - Tell me what you'd like to add
|
||||
> - **9. Sync & Maintain** - Audit & sync all doc surfaces — AGENTS.md, `.agents-docs/`, `specs/`, README, human docs: fix stale/wrong/missing, cut redundancy
|
||||
>
|
||||
> You can also ask me to:
|
||||
> - **Review for corrections** - Check if any existing content is outdated or wrong
|
||||
@@ -105,16 +112,36 @@ Present the user with update options:
|
||||
| Rules | Project-wide or specific? Why? |
|
||||
| Git Commit Messages | Format? Attribution? Conventions? |
|
||||
| Other | "Tell me what to add." |
|
||||
| Sync & Maintain | Scope: all surfaces or specific? Then follow the Sync & Maintain section. |
|
||||
| Review | Per section: "Still accurate?" |
|
||||
| Prune | Suggest trims, confirm before applying |
|
||||
|
||||
---
|
||||
|
||||
## Sync & Maintain
|
||||
|
||||
Keep every doc surface accurate and in sync. **Deep-audit surfaces this session touched; staleness-scan the rest.** Verify against actual code — never assume or fabricate.
|
||||
|
||||
| Surface | Tier | Voice |
|
||||
|---------|------|-------|
|
||||
| `AGENTS.md` + ALL applicable `.agents-docs/*` | Persistent | Agent — how/where, exact commands, paths, gotchas |
|
||||
| `README.md` + human docs | Persistent | Human — what/why, scannable |
|
||||
| Active `specs/<feature>/` | Transient | Session knowledge — status, decisions, next steps. No bloat |
|
||||
|
||||
**Adaptive:** `AGENTS.md`/`.agents-docs/`/`specs/` are plan2code conventions — expected, but verify. `README.md` is standard. Human-docs tree varies (`docs/` or other) — detect, don't assume.
|
||||
|
||||
**Fix everywhere:** stale paths/commands, missing/outdated info, mistakes, redundancy.
|
||||
|
||||
**Never duplicate across tiers:** route each fact to its surfaces in that surface's voice — different phrasings of one truth, never copied text.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Confirm & Apply
|
||||
|
||||
Before changes, route edits to the correct file when `.agents-docs/` exists:
|
||||
- Always-inline sections (Project Overview, Git Commit Messages, How to Use This File) → edit AGENTS.md directly
|
||||
- All other sections → edit the corresponding `.agents-docs/AGENTS-<section-name>.md` file
|
||||
- Sync & Maintain: human-voice facts → README/human docs; session knowledge → active spec's `overview.md`
|
||||
|
||||
Preview format:
|
||||
> **File:** `.agents-docs/AGENTS-architecture.md` (or `AGENTS.md` for inline sections)
|
||||
@@ -206,13 +233,7 @@ CLAUDE.md gets a special template because Claude Code auto-loads it — the `CRI
|
||||
|
||||
**CRITICAL — MANDATORY FIRST STEP: You MUST read [AGENTS.md](./AGENTS.md) before responding to ANY user message, including simple questions. Do NOT skip this step regardless of how trivial the request appears. No exceptions.**
|
||||
|
||||
See AGENTS.md for complete project documentation including:
|
||||
- Development commands and setup
|
||||
- Architecture overview
|
||||
- Environment variables
|
||||
- Testing patterns
|
||||
- Deployment guides
|
||||
- Section details in .agents-docs/
|
||||
See AGENTS.md for full project documentation: commands, architecture, environment, testing, deployment, and .agents-docs/ section details.
|
||||
|
||||
This file exists for Claude Code auto-loading. All AI coding agents should reference AGENTS.md.
|
||||
```
|
||||
@@ -224,13 +245,7 @@ Use title and path from the detection table:
|
||||
```markdown
|
||||
# [Title]
|
||||
|
||||
See [AGENTS.md]([Path]) for complete project documentation including:
|
||||
- Development commands and setup
|
||||
- Architecture overview
|
||||
- Environment variables
|
||||
- Testing patterns
|
||||
- Deployment guides
|
||||
- Section details in .agents-docs/
|
||||
See [AGENTS.md]([Path]) for full project documentation: commands, architecture, environment, testing, deployment, and .agents-docs/ section details.
|
||||
```
|
||||
|
||||
**For directory configs** (`.cursor/rules/`, `.windsurf/rules/`): Delete existing `.md` files, create single `reference.md`.
|
||||
@@ -254,54 +269,31 @@ See [AGENTS.md]([Path]) for complete project documentation including:
|
||||
## Example Session
|
||||
|
||||
```
|
||||
Agent: Found AGENTS.md covering:
|
||||
- Build/test commands
|
||||
- Project structure
|
||||
- API conventions
|
||||
Line count: 127
|
||||
Structure: Single-file (no .agents-docs/ directory)
|
||||
|
||||
Your AGENTS.md uses a single-file format. Want to
|
||||
restructure for progressive discovery?
|
||||
|
||||
User: No thanks, just update it.
|
||||
|
||||
Agent: OK, keeping single-file format.
|
||||
|
||||
Recent work on auth flow. Worth documenting:
|
||||
- JWT refresh token must validate before access token
|
||||
Agent: Found AGENTS.md (127 lines, single-file). Restructure for
|
||||
progressive discovery?
|
||||
User: No, just update it.
|
||||
Agent: Recent work on auth flow. Worth documenting:
|
||||
- Auth tests require TEST_SECRET env var
|
||||
|
||||
Add these?
|
||||
|
||||
User: Yes, both.
|
||||
|
||||
Agent: Adding:
|
||||
|
||||
**Section:** Gotchas
|
||||
```
|
||||
- JWT refresh token must validate before access token in auth flow
|
||||
```
|
||||
|
||||
**Section:** Testing
|
||||
```
|
||||
- Auth tests require TEST_SECRET env variable
|
||||
```
|
||||
|
||||
Add it?
|
||||
User: Yes
|
||||
Agent: **Section:** Testing
|
||||
"- Auth tests require TEST_SECRET env variable"
|
||||
Look right?
|
||||
|
||||
User: Yes
|
||||
|
||||
Agent: Done! Added 2 entries to Gotchas and Testing.
|
||||
Line count: 131/500
|
||||
|
||||
Add anything else?
|
||||
|
||||
Agent: Done! Line count: 128/500. Add anything else?
|
||||
User: No
|
||||
|
||||
Agent: Found CLAUDE.md (23 lines). Replace with AGENTS.md reference?
|
||||
|
||||
User: Yes
|
||||
|
||||
Agent: Updated CLAUDE.md. AGENTS.md is your single source of truth now!
|
||||
```
|
||||
|
||||
## Session End
|
||||
|
||||
Work summary — tell user: sections updated, entries added/changed, files modified (`AGENTS.md` or `.agents-docs/` files).
|
||||
|
||||
Suggested commit:
|
||||
```
|
||||
git commit -m "docs: update AGENTS.md with new learnings" -m "<JIRA-Ticket-ID>" -m "AI Assisted"
|
||||
```
|
||||
|
||||
Returning context: Run `/plan2code-init-update` again to make additional updates.
|
||||
|
||||
@@ -149,3 +149,7 @@ Then tell user: "Created `specs/<feature-name>/PLAN-DRAFT-<date>.md`. Start new
|
||||
```
|
||||
|
||||
Ready to implement? (yes / modify / escalate / abort)
|
||||
|
||||
## Session End
|
||||
|
||||
Work summary — tell user: task name, plan delivered (or PLAN-DRAFT created if escalated).
|
||||
|
||||
+11
-3
@@ -155,9 +155,15 @@ Run every finding through the false-positive detection shortcuts before presenti
|
||||
|
||||
## Session End
|
||||
|
||||
After approval, select template:
|
||||
- **Specs + more phases:** "Next: Phase X. NEW conversation: `/plan2code-3-implement`"
|
||||
- **Specs + all complete:** "All complete! NEW conversation: `/plan2code-4-finalize`"
|
||||
Work summary — tell user: scope reviewed, findings count by severity (Critical/Warning/Suggestion), fixes applied, unresolved findings.
|
||||
|
||||
After approval, select template based on project state:
|
||||
|
||||
**Pre-condition check:** Before suggesting implement or finalize, verify that `overview.md` AND at least one `phase-*.md` file exist in the specs directory. If they do NOT exist, the document step has not been run yet.
|
||||
|
||||
- **Specs dir exists but NO overview.md / phase-*.md files:** "Next: generate implementation docs. NEW conversation: `/plan2code-2-document`"
|
||||
- **Specs + overview.md + phase files + more phases:** "Next: Phase X. NEW conversation: `/plan2code-3-implement`"
|
||||
- **Specs + overview.md + phase files + all complete:** "All complete! NEW conversation: `/plan2code-4-finalize`"
|
||||
- **Standalone:** "Review complete -- [summary]."
|
||||
- **Commit** (code changes): `git add [files] && git commit -m "fix: [desc]" -m "<JIRA>" -m "AI Assisted"` -- derive JIRA from branch.
|
||||
|
||||
@@ -169,6 +175,8 @@ After approval, select template:
|
||||
╰───╯
|
||||
```
|
||||
|
||||
Returning context: Review complete. Unresolved findings documented for follow-up. Run `/plan2code-review` again after addressing follow-up work.
|
||||
|
||||
## Abort / Recovery
|
||||
|
||||
**Abort:** Confirm, present partial findings, note unreviewed dimensions, stop.
|
||||
|
||||
+2
-2
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "1.15.2",
|
||||
"version": "1.15.3",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
@@ -17,7 +17,7 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://plan2code.jparkerweb.com",
|
||||
"releaseDate": "2026-06-01",
|
||||
"releaseDate": "2026-06-28",
|
||||
"mode": "utility"
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user