fix: update execution-plan.md status on stage completion

[inariku]

Problem

When stages complete, aidlc-state.md is updated correctly, but execution-plan.md is never updated. This leaves the execution plan with stale status values (e.g., IN PROGRESS or EXECUTE) even after stages have finished.

Solution

1. Added an instruction to update the corresponding stage status to COMPLETED in aidlc-docs/inception/plans/execution-plan.md at every stage completion point across all rule-details files
2. Explicitly specified (Mermaid flowchart, text alternative, and checklist) to ensure all three representations are updated
3. Added a MANDATORY execution plan tracking principle in core-workflow.md to ensure AI agents prioritize this update

Changes

core-workflow.md (1 file):

• Added Execution Plan Tracking as a MANDATORY Key Principle

Inception phase (7 files):

• workflow-planning.md — update on user approval (numbered sub-list for visibility) + note in execution-plan template
• reverse-engineering.md — Step 10: Update State Tracking
• requirements-analysis.md — approval handling
• user-stories.md — Step 23: Update Progress
• application-design.md — Step 15: Update Progress
• units-generation.md — Step 11 (Units Planning) and Step 19 (Units Generation)

Construction phase (6 files):

• functional-design.md — approval handling
• nfr-requirements.md — approval handling
• nfr-design.md — approval handling
• infrastructure-design.md — approval handling
• code-generation.md — Code Planning (Step 9) and Code Generation completion
• build-and-test.md — Step 8: Update State Tracking

Test Evidence

Tested by running a full AI-DLC workflow (simple TODO CLI app in Python) with the modified rules in Kiro CLI.

Test Setup

• Clean project directory with modified rules copied to .kiro/steering/ and .kiro/aws-aidlc-rule-details/
• Ran: Using AI-DLC, create a simple TODO list CLI app in Python

Results — execution-plan.md status updates

Stage	Mermaid Flowchart	Checklist
Workflow Planning (approve)	✅ IN PROGRESS → COMPLETED	✅ Updated
Code Generation (completion)	✅ EXECUTE → COMPLETED	✅ EXECUTE → COMPLETED

Before (Workflow Planning created, before approve)

L26: WP["Workflow Planning<br/><b>IN PROGRESS</b>"]
L71: - [x] Workflow Planning (IN PROGRESS)
L30: CG["Code Generation<br/><b>EXECUTE</b>"]
L89: - [ ] Code Generation - EXECUTE (ALWAYS)

After (Code Generation completed)

L26: WP["Workflow Planning<br/><b>COMPLETED</b>"]
L71: - [x] Workflow Planning (COMPLETED)
L30: CG["Code Generation<br/><b>COMPLETED</b>"]
L89: - [x] Code Generation - COMPLETED

Key Findings

• The MANDATORY principle in core-workflow.md was essential for making the AI consistently perform the updates. Without it (tested in earlier iterations), the AI skipped the execution-plan.md updates despite instructions in individual stage files.
• Initial testing only specified "Mermaid flowchart and checklist", which left the text alternative section stale. Updated all instructions to include text alternative as well.

Closes #23

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[inariku]

Hey @raj-jain-aws 👋 Same ask as #68 — would appreciate a merge commit instead of squash so the contribution shows up. Thanks!

[scottschreckengaust]

Hi @inariku. You are already a contributor. We squash commits that show contribution, this PR shows your participation (no commits).

[Copilot]

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

[harmjeff]

@inariku Can you confirm if this issue is still a problem, if so I will approve

[scottschreckengaust]

LGTM

[harmjeff]

@inariku Please resolve the conflicts

[inariku]

@harmjeff Yes, the issue is still present — upstream main has no instructions to update execution-plan.md on stage completion. I've rebased and resolved the conflicts. Ready for review!

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 13 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The new mandatory principle requires updating the execution plan to COMPLETED on “ANY stage completion”, but several CONSTRUCTION stages are explicitly per-unit (see common/process-overview.md). If agents follow this literally, they may mark a stage COMPLETED in execution-plan.md after finishing the first unit, even though other units remain. Consider tightening the wording to clarify that execution-plan.md should only be updated to COMPLETED when the stage is complete for the overall workflow (e.g., last unit completed), or update the execution-plan format to track per-unit progress.

Suggested change

- **Execution Plan Tracking**: When completing ANY stage, update that stage's status to COMPLETED in `aidlc-docs/inception/plans/execution-plan.md` (Mermaid flowchart, text alternative, and checklist). This is MANDATORY for every stage completion.

- **Execution Plan Tracking**: When a stage is FULLY COMPLETE for the overall workflow (e.g., all units finished for per-unit CONSTRUCTION stages), update that stage's status to COMPLETED in `aidlc-docs/inception/plans/execution-plan.md` (Mermaid flowchart, text alternative, and checklist). This is MANDATORY for every overall stage completion; do NOT mark a stage COMPLETED in the execution plan based only on the first or partial unit being finished.

[Copilot]

This note (and the new stage-completion instructions) refer to updating a “text alternative” in execution-plan.md, but the execution-plan template defined in Step 7 currently includes only the Mermaid flowchart and the checklist sections (no dedicated text-alternative section). To make this requirement actionable, consider adding an explicit text-alternative section to the template (and clarifying what it should contain) or removing/renaming the reference here to match the actual template structure.

Suggested change

	**Note**: Replace STATUS placeholders with actual phase status (COMPLETED/SKIP/EXECUTE) and apply appropriate styling. When updating a stage status to COMPLETED, update it in the Mermaid flowchart, text alternative, and checklist.
	**Note**: Replace STATUS placeholders with actual phase status (COMPLETED/SKIP/EXECUTE) and apply appropriate styling. When updating a stage status to COMPLETED, update it in the Mermaid flowchart, the Text Alternative section below, and the checklist.
	## Text Alternative for Workflow Diagram
	Provide a concise text description of the workflow for accessibility (for example, for screen readers). At minimum, list each phase and the status of its stages in reading order.
	- **Inception Phase**:
	- Workspace Detection – [STATUS]
	- Reverse Engineering – [STATUS]
	- Requirements Analysis – [STATUS]
	- User Stories – [STATUS]
	- Workflow Planning – [STATUS]
	- Application Design – [STATUS]
	- Units Planning – [STATUS]
	- Units Generation – [STATUS]
	- **Construction Phase**:
	- Functional Design – [STATUS]
	- NFR Requirements – [STATUS]
	- NFR Design – [STATUS]
	- Infrastructure Design – [STATUS]
	- Code Generation – [STATUS]
	- Build and Test – [STATUS]
	- **Operations Phase**:
	- Operations – [STATUS]

[Copilot]

In the execution-plan template’s checklist, the INCEPTION item is currently “Execution Plan (IN PROGRESS)” rather than “Workflow Planning (IN PROGRESS)”, so the instruction here to update Workflow Planning in the checklist is ambiguous/non-actionable. Either update the execution-plan checklist template to include a “Workflow Planning” entry (and align naming with the flowchart WP node), or adjust this instruction to match the checklist item name that actually exists.

Suggested change

	1. Update Workflow Planning status from IN PROGRESS to COMPLETED in `aidlc-docs/inception/plans/execution-plan.md` (Mermaid flowchart, text alternative, and checklist)
	1. Update the INCEPTION checklist item "Execution Plan" status from IN PROGRESS to COMPLETED in `aidlc-docs/inception/plans/execution-plan.md` (Mermaid flowchart, text alternative, and checklist)

[Copilot]

This stage is “Code Generation” in execution-plan.md (the template shows a single node: “Code Generation (Planning + Generation)”), so asking to mark “Code Generation Part 1 (Planning)” as COMPLETED in execution-plan.md doesn’t match any stage/status in that file. Also, marking the stage COMPLETED at the end of planning would be premature (generation hasn’t happened yet). Suggest removing this execution-plan update from Part 1, or updating the execution-plan format to explicitly track Part 1 vs Part 2 if that’s the intent.

Suggested change

	- [ ] Update Code Generation Part 1 (Planning) status to COMPLETED in `aidlc-docs/inception/plans/execution-plan.md` (Mermaid flowchart, text alternative, and checklist)
	- [ ] Update the "Current Status" section
	- [ ] Keep `aidlc-docs/inception/plans/execution-plan.md` using a single "Code Generation (Planning + Generation)" stage; do not mark Code Generation as COMPLETED until Part 2 (Generation) is finished
	- [ ] Update the "Current Status" section in `aidlc-state.md` to reflect that planning is complete and generation is ready to start

[Copilot]

Code Generation is defined as an ALWAYS, per-unit stage (common/process-overview.md). Updating the single “Code Generation” status in execution-plan.md to COMPLETED at the end of each unit risks marking the overall stage done while other units remain. Consider gating this update so it only flips to COMPLETED once the final unit’s code generation is approved, or revise execution-plan.md to track per-unit progress explicitly.

Suggested change

	- Update Code Generation status to COMPLETED in `aidlc-docs/inception/plans/execution-plan.md` (Mermaid flowchart, text alternative, and checklist)
	- Only when **all units' Code Generation** is approved, update the global Code Generation status to COMPLETED in `aidlc-docs/inception/plans/execution-plan.md` (Mermaid flowchart, text alternative, and checklist). Otherwise, leave the global status as IN PROGRESS and track per-unit completion in `aidlc-state.md`.

[Copilot]

Infrastructure Design is a per-unit stage (common/process-overview.md). Updating the single “Infrastructure Design” status in execution-plan.md to COMPLETED at the end of one unit could incorrectly show the overall stage as done while other units remain. Consider only marking COMPLETED in execution-plan.md once all units have finished Infrastructure Design, or update the execution plan to track per-unit completion.

Suggested change

	- Update Infrastructure Design status to COMPLETED in `aidlc-docs/inception/plans/execution-plan.md` (Mermaid flowchart, text alternative, and checklist)
	- Update Infrastructure Design status in `aidlc-docs/inception/plans/execution-plan.md` (Mermaid flowchart, text alternative, and checklist) **only when Infrastructure Design is complete for all units**; otherwise, ensure any per-unit tracking in the execution plan is updated for the current unit

[Copilot]

The workflow’s directory structure places the canonical state file at aidlc-docs/aidlc-state.md (core-workflow.md “Directory Structure”). This step still references aidlc-state.md without the aidlc-docs/ prefix, which can lead agents to write/update the wrong file. Consider updating this reference to aidlc-docs/aidlc-state.md for consistency with other stages.

Suggested change

	- Mark User Stories stage complete in `aidlc-state.md`
	- Mark User Stories stage complete in `aidlc-docs/aidlc-state.md`

[Copilot]

This step still says “Mark Units Planning complete in aidlc-state.md” (no aidlc-docs/ prefix), while the canonical path in the workflow is aidlc-docs/aidlc-state.md (core-workflow.md “Directory Structure”). Since this step is being touched, consider updating the state-file reference here to the canonical path to avoid creating/updating the wrong file.

Suggested change

	- Mark Units Planning complete in aidlc-state.md
	- Mark Units Planning complete in aidlc-docs/aidlc-state.md

[Copilot]

For consistency with the surrounding “Update State Tracking” step (which is a bulleted checklist), consider making this new execution-plan update instruction a bullet in the same list (rather than a standalone sentence between code fences/headings). That makes it less likely to be missed during stage completion.

[Copilot]

This completion checklist still references “aidlc-state.md” without the canonical aidlc-docs/ prefix, even though earlier in this file Step 8 updates aidlc-docs/aidlc-state.md and the core workflow’s directory structure puts the file under aidlc-docs/. Consider updating this line to aidlc-docs/aidlc-state.md to avoid ambiguity about which file should be edited.

Suggested change

	- Update Requirements Analysis stage complete in aidlc-state.md
	- Update Requirements Analysis stage complete in `aidlc-docs/aidlc-state.md`