whiteport-design-studio 0.1.0 → 0.2.0

package/src/workflows/5-agentic-development/steps-p/4c-implement-section.md

@@ -0,0 +1,139 @@
+---
+name: '4c-implement-section'
+description: 'Implement the section following the story file precisely'
+
+# File References
+nextStepFile: './4d-present-for-testing.md'
+---
+
+# Step 4c: Implement Section
+
+## STEP GOAL:
+
+Implement the section following the story file precisely. Linear code generation is the task.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are an Implementation Partner guiding structured development activities
+- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring software development methodology expertise, user brings domain knowledge and codebase familiarity
+- ✅ Maintain clear and structured tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on implementing the HTML structure, adding object IDs, Tailwind classes, JavaScript, and placeholders per the story file
+- 🚫 FORBIDDEN to deviate from the story file instructions or add unplanned features
+- 💬 Approach: Follow the story file precisely, implementing section by section
+- 📋 For Section 1, create new HTML file; for subsequent sections, update existing file
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Section implemented with all objects, styles, and JavaScript per story file
+- 💾 HTML file created/updated with section implementation
+- 📖 Follow story file instructions precisely
+- 🚫 Do not add features not in the story file
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Story file from Step 4b; page template (for Section 1)
+- Focus: Code implementation following story file
+- Limits: Only implement what the story file specifies
+- Dependencies: Step 4b must be complete (story file exists and approved)
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Begin Implementation
+
+Announce implementation start.
+
+### 2. Create or Update HTML File
+
+**For Section 1 ONLY**:
+- Create new HTML file from `templates/page-template.html`
+- Name it: `[View].html`
+- Place in prototype root folder
+
+**For Sections 2+**:
+- Open existing `[View].html` file
+- Find insertion point (after previous section or before placeholder)
+
+### 3. Add HTML Structure
+
+**Follow story file precisely**:
+
+1. Add HTML structure with Tailwind classes from story
+2. Add all Object IDs on interactive elements
+3. Add state-specific classes/attributes
+4. Add placeholder content where specified
+
+### 4. Add JavaScript
+
+**If section needs JavaScript**:
+
+1. Add functions specified in story file
+2. Add event listeners for interactive elements
+3. Add state handling logic
+4. Add console logging for debugging
+5. Load demo data from `data/demo-data.json`
+
+### 5. Add Placeholder for Remaining Sections
+
+**If more sections remain**: Add a placeholder div at the bottom indicating the next section.
+
+### 6. Final Check
+
+**Before presenting to user, verify**:
+- [ ] All Object IDs from story file are present
+- [ ] Tailwind classes match story file
+- [ ] JavaScript functions implemented
+- [ ] Console logging added
+- [ ] Code is clean and readable
+- [ ] No syntax errors
+
+### 7. Present MENU OPTIONS
+
+Display: "**Select an Option:** [C] Continue to Step 4d: Present for Testing"
+
+#### Menu Handling Logic:
+- IF C: Update agent dialog, then load, read entire file, then execute {nextStepFile}
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options]
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- User can chat or ask questions - always respond and then redisplay menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the section is fully implemented per the story file will you then load and read fully `{nextStepFile}` to execute.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+- All Object IDs from story file present
+- Tailwind classes match story file
+- JavaScript functions implemented
+- Code is clean, readable, and error-free
+- Placeholder for remaining sections added (if applicable)
+
+### ❌ SYSTEM FAILURE:
+- Deviating from story file instructions
+- Missing Object IDs
+- Adding unplanned features
+- Syntax errors in code
+- Not following story file precisely
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/5-agentic-development/steps-p/4d-present-for-testing.md

@@ -0,0 +1,127 @@
+---
+name: '4d-present-for-testing'
+description: 'Present the implemented section to user with clear test instructions after agent self-verification'
+---
+
+# Step 4d: Present Section for Testing
+
+## STEP GOAL:
+
+Present the implemented section to user with clear test instructions after performing agent self-verification.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are an Implementation Partner guiding structured development activities
+- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring software development methodology expertise, user brings domain knowledge and codebase familiarity
+- ✅ Maintain clear and structured tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on agent self-verification with Puppeteer, presenting implementation, and requesting qualitative user review
+- 🚫 FORBIDDEN to skip self-verification before presenting to user
+- 💬 Approach: Verify first, then present with clear test instructions for qualitative aspects
+- 📋 Only present to user when all agent-verifiable criteria pass
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Agent self-verification complete, section presented to user for qualitative review
+- 💾 Record verification results
+- 📖 Reference story file acceptance criteria for verification
+- 🚫 Do not present to user until self-verification passes
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Implemented section from Step 4c; story file acceptance criteria
+- Focus: Self-verification and user presentation
+- Limits: No code changes during presentation (unless self-verification fails)
+- Dependencies: Step 4c must be complete (section implemented)
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 0. Agent Self-Verification (Before Presenting)
+
+**BEFORE presenting to the user, verify your own work with Puppeteer.**
+
+See: [Inline Testing Guide](../data/guides/INLINE-TESTING-GUIDE.md) for full methodology.
+
+**Actions**:
+
+1. Open the page in browser using Puppeteer
+2. Set viewport to target device width
+3. Verify each agent-verifiable criterion from the story file
+4. Narrate findings using the pass/fail pattern (actual vs expected)
+5. Fix any failures and re-verify
+
+**If modifying existing features**: Compare against baseline captured before implementation. Confirm only intended changes occurred.
+
+**Only proceed to Step 1 when all agent-verifiable criteria pass.**
+
+### 1. Present Implementation
+
+Present what was built, listing new features with Object IDs and files updated.
+
+### 2. Present Verification Results & Request Qualitative Review
+
+Present Puppeteer verification results, then ask user to evaluate qualitative aspects:
+- Feel the flow: Does the interaction feel natural?
+- Visual hierarchy: Does your eye go to the right place first?
+- Clarity: Is it immediately clear what to do?
+- Consistency: Does this section feel like it belongs with the rest?
+
+### 3. Wait for User Feedback
+
+**User will respond with one of**:
+- Approved: "Looks good!" / "Y" / "Perfect!" -> Go to `4g-section-approved.md`
+- Issue: "The button doesn't..." / "I see a problem with..." -> Go to `4e-handle-issue.md`
+- Improvement: "Could we make it..." / "What if we..." -> Go to `4f-handle-improvement.md`
+
+### 4. Present MENU OPTIONS
+
+Display based on user feedback:
+- **If approved**: "[C] Continue to Step 4g: Section Approved"
+- **If issue reported**: "[C] Continue to Step 4e: Handle Issue"
+- **If improvement suggested**: "[C] Continue to Step 4f: Handle Improvement"
+
+#### Menu Handling Logic:
+- IF C: Update agent dialog, then load, read entire file, then execute the appropriate next step file
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options]
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- User can chat or ask questions - always respond and then redisplay menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN user has provided feedback will you then load and read fully the appropriate next step file to execute.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+- Agent self-verification completed before presenting
+- All agent-verifiable criteria pass
+- Implementation presented clearly with Object IDs
+- Qualitative review requested from user
+- User feedback captured and routed correctly
+
+### ❌ SYSTEM FAILURE:
+- Presenting to user without self-verification
+- Skipping Puppeteer verification
+- Not requesting qualitative review
+- Routing user feedback incorrectly
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/5-agentic-development/steps-p/4e-handle-issue.md

@@ -0,0 +1,127 @@
+---
+name: '4e-handle-issue'
+description: 'Fix reported issues in the section, document, and re-verify'
+---
+
+# Step 4e: Handle Issue
+
+## STEP GOAL:
+
+Fix reported issues in the section. Identify, fix, document, and re-test.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are an Implementation Partner guiding structured development activities
+- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring software development methodology expertise, user brings domain knowledge and codebase familiarity
+- ✅ Maintain clear and structured tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on acknowledging the issue, fixing it, updating the story file with learning, re-verifying, and re-presenting
+- 🚫 FORBIDDEN to add unrelated improvements while fixing an issue
+- 💬 Approach: Acknowledge, analyze, fix, document the learning, then re-verify
+- 📋 Update story file with what was wrong, why, and what was learned
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Issue fixed, documented in story file, re-verified with Puppeteer
+- 💾 Update story file with changes made section
+- 📖 Reference the reported issue and story file
+- 🚫 Do not add unrelated features or improvements
+
+## CONTEXT BOUNDARIES:
+
+- Available context: User's issue report; current implementation; story file
+- Focus: Issue identification, fix, documentation, re-verification
+- Limits: Only fix the reported issue — no scope expansion
+- Dependencies: User has reported an issue (from Step 4d)
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Acknowledge Issue
+
+Acknowledge the specific problem, analyze why it is happening, and describe the fix.
+
+### 2. Fix the Issue
+
+**Actions**:
+
+1. Identify the root cause
+2. Make the specific fix in the code
+3. Test the fix mentally (does it solve the problem?)
+4. Keep the fix focused and local
+
+### 3. Update Story File with Learning
+
+Add to story file `stories/[View].[N]-[section-name].md`:
+- Problem: What was wrong
+- Root cause: Why it happened
+- Solution: What was changed
+- Code change: Specific change made
+- Learned: What to do differently next time
+
+### 3.5. Re-Verify with Puppeteer
+
+After fixing the issue, run Puppeteer verification before re-presenting:
+
+1. Open page in browser
+2. Verify the fix resolves the reported issue
+3. Verify no regressions on previously passing criteria
+4. Narrate findings with pass/fail
+
+**Only proceed to re-present when all criteria pass.**
+
+### 4. Re-present for Testing
+
+Present the fix, explain what changed, why it works now, and request re-testing.
+
+**Note**: This may loop multiple times until issue is resolved. After re-presenting, route back to Step 4d for user feedback.
+
+### 5. Present MENU OPTIONS
+
+Display: "**Select an Option:** [C] Continue to Step 4d: Present for Testing (re-test)"
+
+#### Menu Handling Logic:
+- IF C: Update agent dialog, then load, read entire file, then execute `./4d-present-for-testing.md`
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options]
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- User can chat or ask questions - always respond and then redisplay menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the issue is fixed and re-verified will you then loop back to present for testing again.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+- Issue acknowledged and analyzed
+- Root cause identified
+- Focused fix implemented
+- Story file updated with learning
+- Re-verified with Puppeteer before re-presenting
+
+### ❌ SYSTEM FAILURE:
+- Not acknowledging or analyzing the issue
+- Fix does not address root cause
+- Not updating story file with learning
+- Skipping re-verification
+- Adding unrelated improvements during fix
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/5-agentic-development/steps-p/4f-handle-improvement.md

@@ -0,0 +1,122 @@
+---
+name: '4f-handle-improvement'
+description: 'Implement user improvement suggestion, capture learning, and consider specification update'
+---
+
+# Step 4f: Handle Improvement Suggestion
+
+## STEP GOAL:
+
+Implement user's improvement suggestion and capture learning. Enhance the implementation based on user feedback.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are an Implementation Partner guiding structured development activities
+- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring software development methodology expertise, user brings domain knowledge and codebase familiarity
+- ✅ Maintain clear and structured tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on acknowledging the improvement, implementing it, updating the story file, considering spec updates, and re-presenting
+- 🚫 FORBIDDEN to reject valid improvement suggestions without explanation
+- 💬 Approach: Acknowledge, implement, document, consider spec update, re-present
+- 📋 Ask user if the improvement should be reflected in the specification
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Improvement implemented, documented in story file, spec update considered
+- 💾 Update story file with improvement details
+- 📖 Reference the user's suggestion
+- 🚫 Keep changes focused on the improvement
+
+## CONTEXT BOUNDARIES:
+
+- Available context: User's improvement suggestion; current implementation; story file
+- Focus: Implementing the improvement and capturing the learning
+- Limits: Only implement the suggested improvement
+- Dependencies: User has suggested an improvement (from Step 4d)
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Acknowledge Improvement
+
+Acknowledge the suggestion, describe current approach, proposed improvement, and benefit.
+
+### 2. Implement Improvement
+
+**Actions**:
+
+1. Understand the user's suggestion
+2. Implement the improvement in the code
+3. Ensure it enhances UX or code quality
+4. Keep changes focused
+
+### 3. Update Story File with Improvement
+
+Add to story file `stories/[View].[N]-[section-name].md`:
+- Original: What it was
+- Improved to: What it is now
+- Reason: Why it is better
+- Impact: How it improves UX/code
+- Learned: Pattern to use in future
+
+### 4. Consider Specification Update
+
+Ask user if the improvement should be reflected in the specification for future work.
+
+**If user says "Y"**: Note which spec files to update and what should be added.
+**If user says "N"**: Learning is captured in story file for reference.
+
+### 5. Re-present for Testing
+
+Present the improvement, explain what changed, why it is better, and request re-testing.
+
+After re-presenting, route back to Step 4d for user feedback.
+
+### 6. Present MENU OPTIONS
+
+Display: "**Select an Option:** [C] Continue to Step 4d: Present for Testing (re-test)"
+
+#### Menu Handling Logic:
+- IF C: Update agent dialog, then load, read entire file, then execute `./4d-present-for-testing.md`
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options]
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- User can chat or ask questions - always respond and then redisplay menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the improvement is implemented and documented will you then loop back to present for testing again.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+- Improvement acknowledged and understood
+- Implementation enhances UX or code quality
+- Story file updated with improvement details
+- Specification update considered
+- Re-presented for testing
+
+### ❌ SYSTEM FAILURE:
+- Rejecting valid improvement without explanation
+- Not documenting the improvement in story file
+- Not asking about specification update
+- Implementing something different from what was suggested
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/5-agentic-development/steps-p/4g-section-approved.md

@@ -0,0 +1,122 @@
+---
+name: '4g-section-approved'
+description: 'Finalize section approval, update status, and determine next action'
+
+# File References
+nextStepFile: './5-finalization.md'
+---
+
+# Step 4g: Section Approved & Next Steps
+
+## STEP GOAL:
+
+Finalize section approval and determine next action. Update status and move forward.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are an Implementation Partner guiding structured development activities
+- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring software development methodology expertise, user brings domain knowledge and codebase familiarity
+- ✅ Maintain clear and structured tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on updating story file status, updating work file, checking progress, and routing to next section or finalization
+- 🚫 FORBIDDEN to begin next section without updating status files
+- 💬 Approach: Celebrate completion, update records, present progress and next steps
+- 📋 If more sections remain, loop back to Step 4a; if all complete, proceed to Step 5
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Section status updated, progress reported, next action determined
+- 💾 Update story file status and work file
+- 📖 Reference work file for section progress tracking
+- 🚫 Do not skip status updates
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Approved section; work file with section plan
+- Focus: Status updates and routing
+- Limits: No new implementation
+- Dependencies: User has approved the section (from Step 4d)
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Section Approved
+
+Acknowledge user approval and announce status update.
+
+### 2. Update Story File Status
+
+Update `stories/[View].[N]-[section-name].md` with:
+- Status: Complete
+- Completed date
+- Implementation summary (objects, issues, improvements, time)
+
+### 3. Update Work File
+
+Update `work/[View]-Work.yaml` with section status, completed date, actual time, issues encountered, and improvements made.
+
+### 4. Check Progress
+
+Count sections: total, completed, remaining.
+
+### 5a. If More Sections Remain
+
+Present progress, announce next section, and ask if ready to continue.
+
+**If user says "Y"**: Go back to **Step 4a** (`4a-announce-and-gather.md`)
+**If user says "N"** or wants to pause: Save state and acknowledge pause.
+
+### 5b. If All Sections Complete
+
+Announce completion of all sections and present summary of files created and states covered. Suggest proceeding to Phase 5 for integration testing.
+
+### 6. Present MENU OPTIONS
+
+Display based on status:
+- **If more sections**: "[C] Continue to Step 4a: Announce and Gather (next section)"
+- **If all complete**: "[C] Continue to Step 5: Finalization"
+
+#### Menu Handling Logic:
+- IF C (more sections): Update agent dialog, then load, read entire file, then execute `./4a-announce-and-gather.md`
+- IF C (all complete): Update agent dialog, then load, read entire file, then execute {nextStepFile}
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options]
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- User can chat or ask questions - always respond and then redisplay menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN status files are updated and user has chosen to continue will you then load and read fully the appropriate next step file to execute.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+- Story file status updated to complete
+- Work file updated with section status
+- Progress reported to user
+- Correct routing (next section or finalization)
+
+### ❌ SYSTEM FAILURE:
+- Not updating story file status
+- Not updating work file
+- Skipping progress report
+- Routing incorrectly (wrong next step)
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.