whiteport-design-studio 0.1.0

package/src/workflows/9-agent-dialogs/steps/step-02-analyze-scope.md

@@ -0,0 +1,195 @@
+# Step 2: Analyze Scope
+
+## CONTEXT
+
+Dialog folder is created. Now we analyze the specification to determine exactly what needs to be implemented.
+
+---
+
+## READ SPECIFICATION
+
+<action>
+**Read the specification file(s)** referenced in the dialog file.
+
+Extract:
+- All features/sections to implement
+- Object IDs and their specifications
+- States and transitions
+- Translations required
+- Any open questions in the spec
+</action>
+
+---
+
+## IDENTIFY SCOPE
+
+<ask>**What should be IN SCOPE for this implementation?**
+
+Based on the specification, list the features/sections to implement.
+
+In scope:</ask>
+
+<action>Store in_scope items</action>
+
+<ask>**What should be OUT OF SCOPE?**
+
+Explicitly list what we're NOT implementing (yet).
+
+Out of scope:</ask>
+
+<action>Store out_of_scope items</action>
+
+<ask>**Are there any dependencies?**
+
+What must exist before we can implement this? (Other features, data, APIs, etc.)
+
+Dependencies:</ask>
+
+<action>Store dependencies</action>
+
+---
+
+## CHECK FOR ISSUES
+
+<action>
+**Review the specification for:**
+
+1. **Missing information** — Anything unclear or undefined?
+2. **Open questions** — Any unresolved decisions?
+3. **Inconsistencies** — Anything that doesn't match?
+
+Document any issues found.
+</action>
+
+<check if="issues_found">
+  <ask>**Issues found in specification:**
+
+  {{#each issue in issues}}
+  - {{issue}}
+  {{/each}}
+
+  How should we proceed?
+
+  [A] Continue anyway — address issues as we go
+  [B] Pause — clarify issues before proceeding
+  [C] Document issues — continue but note them
+
+  Choice:</ask>
+</check>
+
+---
+
+## UPDATE DIALOG FILE
+
+<action>
+**Update the Scope section in the dialog file:**
+
+### In Scope
+{{#each item in in_scope}}
+- {{item}}
+{{/each}}
+
+### Out of Scope
+{{#each item in out_of_scope}}
+- {{item}}
+{{/each}}
+
+### Dependencies
+{{#each item in dependencies}}
+- {{item}}
+{{/each}}
+</action>
+
+---
+
+## DETERMINE STEP BREAKDOWN
+
+<action>
+**Analyze the scope to identify discrete steps.**
+
+Guidelines:
+- Each step should accomplish ONE clear thing
+- Steps should be ~15-45 minutes of work
+- Order by dependencies (what must come first)
+- Group related changes together
+- Consider testability (each step should be verifiable)
+
+**Common patterns:**
+
+For UI features:
+1. Shell/container component
+2. Static content sections
+3. Dynamic data integration
+4. Interactive elements
+5. State transitions
+6. Edge cases / error states
+
+For refactoring:
+1. Create new structure
+2. Migrate piece 1
+3. Migrate piece 2
+4. Remove old structure
+5. Update imports/references
+
+For bug fixes:
+1. Reproduce issue
+2. Implement fix
+3. Add tests
+4. Verify fix
+</action>
+
+<ask>**What steps do we need?**
+
+Based on the scope, list the implementation steps in order.
+
+Example:
+1. Drawer shell component
+2. Header section
+3. Date display section
+4. Dog info section
+5. Action buttons
+6. State transitions
+
+Steps:</ask>
+
+<action>Store steps list</action>
+
+---
+
+## COMPLETION
+
+<output>
+✅ **Scope analyzed!**
+
+**In Scope:** {{in_scope.length}} items
+**Out of Scope:** {{out_of_scope.length}} items
+**Dependencies:** {{dependencies.length}} items
+
+**Proposed Steps:**
+{{#each step in steps}}
+{{@index + 1}}. {{step}}
+{{/each}}
+
+**Next:** Create step files for each implementation step.
+
+[A] Continue to Step 3: Create Step Files
+[B] Adjust the step breakdown
+[C] Review scope again
+
+Choice:
+</output>
+
+---
+
+## ROUTING
+
+<action>
+Based on user choice:
+- [A] → Load and execute step-03-create-steps.md
+- [B] → Allow user to modify steps list
+- [C] → Return to scope review
+</action>
+
+---
+
+_Agent Dialog Workflow — Step 2: Analyze Scope_

package/src/workflows/9-agent-dialogs/steps/step-03-create-steps.md

@@ -0,0 +1,186 @@
+# Step 3: Create Step Files
+
+## CONTEXT
+
+Scope is analyzed and steps are identified. Now we create the step files that will guide implementation.
+
+---
+
+## CREATE STEP FILES
+
+<action>
+**For each step identified in Step 2:**
+
+1. Create file: `steps/{##}-{step-slug}.md`
+2. Use template from: `templates/step.template.md`
+3. Fill in all sections
+
+**File naming:**
+- `##` = Two-digit step number (01, 02, 03, etc.)
+- `{step-slug}` = Step name, lowercase, hyphenated
+
+**Example:** `steps/01-drawer-shell.md`
+</action>
+
+---
+
+## STEP FILE CONTENT
+
+For each step file, fill in:
+
+### Context Section
+
+<action>
+Write a brief paragraph explaining:
+- What exists at this point
+- What this step adds
+- Why this step is needed
+</action>
+
+### Specification Reference
+
+<action>
+Extract the relevant section from the specification:
+- Object IDs
+- Properties and values
+- Translation keys
+- Behaviors
+</action>
+
+### Task Section
+
+<action>
+Write clear objectives:
+- What specifically to implement
+- Numbered list of 2-5 objectives
+- Concrete and actionable
+</action>
+
+### Files to Modify
+
+<action>
+Create a table listing:
+- Each file to create or modify
+- Action (Create / Modify)
+- Purpose of the change
+</action>
+
+### Implementation Details
+
+<action>
+Provide specific guidance:
+- Approach to take
+- Code patterns to follow
+- Important considerations
+- Example code if helpful
+</action>
+
+### Acceptance Criteria
+
+<action>
+Write verifiable criteria:
+- Specific outcomes to check
+- Each criterion is pass/fail
+- Include "No TypeScript errors"
+- Include "UI matches specification"
+</action>
+
+### Test Instructions
+
+<action>
+Write testing steps:
+1. How to trigger the feature
+2. What to check
+3. Expected result
+4. Edge cases to verify
+</action>
+
+---
+
+## SELF-CONTAINED PRINCIPLE
+
+<important>
+**Each step file must be self-contained.**
+
+An agent with NO prior context should be able to:
+1. Read the step file
+2. Understand what to do
+3. Execute the implementation
+4. Verify it works
+
+If a step requires context from previous steps, include it explicitly.
+</important>
+
+---
+
+## UPDATE DIALOG FILE
+
+<action>
+**Update the Steps Overview table:**
+
+| # | Step | Status | Notes |
+|---|------|--------|-------|
+{{#each step in steps}}
+| {{@index + 1}} | [{{step.name}}](steps/{{step.file}}) | 🔲 | |
+{{/each}}
+</action>
+
+---
+
+## REVIEW STEP FILES
+
+<action>
+**Quality check each step file:**
+
+- [ ] Context is clear
+- [ ] Specification reference is accurate
+- [ ] Task objectives are specific
+- [ ] Files to modify are listed
+- [ ] Implementation details are helpful
+- [ ] Acceptance criteria are verifiable
+- [ ] Test instructions are complete
+</action>
+
+---
+
+## COMPLETION
+
+<output>
+✅ **Step files created!**
+
+**Created {{steps.length}} step files:**
+{{#each step in steps}}
+- `steps/{{step.file}}` — {{step.name}}
+{{/each}}
+
+**Dialog file updated** with Steps Overview table.
+
+**Ready for implementation!**
+
+---
+
+**Options:**
+
+[A] Start implementing — Execute Step 1
+[B] Review a specific step file
+[C] Modify a step file
+[D] Exit — Continue later
+
+Choice:
+</output>
+
+---
+
+## ROUTING
+
+<action>
+Based on user choice:
+- [A] → Load and execute step-04-execute-steps.md (with step 1)
+- [B] → Show requested step file
+- [C] → Edit requested step file
+- [D] → End workflow, user will continue later
+</action>
+
+---
+
+_Agent Dialog Workflow — Step 3: Create Step Files_

package/src/workflows/9-agent-dialogs/steps/step-04-execute-steps.md

@@ -0,0 +1,250 @@
+# Step 4: Execute Steps
+
+## CONTEXT
+
+Step files are created. Now we execute each step, either in this dialog or in fresh agent dialogs.
+
+**Note:** For implementation-specific execution details (feedback protocol, dynamic planning), see the **Agentic Development Workflow** in `workflows/4-ux-design/agentic-development/workflow.md`.
+
+---
+
+## EXECUTION MODES
+
+### Mode A: Continuous Execution
+Execute all steps in the current session.
+- ✅ Good for: Small implementations, full context available
+- ❌ Risk: Context window limits, fatigue
+
+### Mode B: Fresh Dialog Per Step
+Start a new agent dialog for each step.
+- ✅ Good for: Large implementations, complex steps
+- ✅ Benefit: Fresh context, isolated focus
+- ❌ Requires: Well-written self-contained step files
+
+<ask>**Which execution mode?**
+
+[A] Continuous — Execute steps in this session
+[B] Fresh dialogs — I'll execute each step in a new dialog
+
+Mode:</ask>
+
+---
+
+## MODE A: CONTINUOUS EXECUTION
+
+### Execute Current Step
+
+<action>
+1. **Read the step file** completely
+2. **Document any decisions or issues** in the dialog before implementing
+3. **Execute the implementation** following the instructions
+4. **Add sub-steps** if needed for things discovered during implementation
+5. **Verify against acceptance criteria**
+6. **Test using the test instructions**
+</action>
+
+### Step Completion Checklist
+
+- [ ] All objectives achieved
+- [ ] Acceptance criteria pass
+- [ ] Tests pass
+- [ ] No TypeScript errors
+- [ ] Code follows existing patterns
+
+### Update Dialog File
+
+<action>
+**After completing each step:**
+
+1. Update step status: 🔲 → ✅
+2. Add notes if relevant
+3. Add entry to Progress Log:
+   ```
+   ### {today's date}
+   - Completed Step {N}: {step name}
+   - {any notes or discoveries}
+   ```
+</action>
+
+### Continue or Pause
+
+<ask>**Step complete! What's next?**
+
+[A] Continue to next step
+[B] Pause — save progress and continue later
+[C] Review what was done
+
+Choice:</ask>
+
+<check if="choice == A">
+  <action>
+  1. Review and update remaining steps in dialog file
+  2. Load and execute next step file
+  </action>
+</check>
+
+<check if="choice == B">
+  <action>
+  Update dialog file:
+  - Status: "In Progress"
+  - Progress Log: Note where we stopped
+  - Ensure all decisions documented
+
+  Output: "Progress saved. The dialog is ready to resume."
+  </action>
+</check>
+
+---
+
+## MODE B: FRESH DIALOG INSTRUCTIONS
+
+### Handoff Always References Dialog
+
+<warning>
+**Any handoff — to a new session, new agent, or human — MUST reference the dialog document.**
+
+The dialog document is the single source of truth for:
+- What has been done
+- What decisions were made
+- What remains to be done
+- Any issues or blockers
+
+Never hand off by describing the task verbally. Always point to the dialog.
+</warning>
+
+### For Each Step
+
+<action>
+**Generate handoff instructions:**
+
+```
+## Execute Step {N}: {Step Name}
+
+### Dialog Document (READ FIRST)
+`docs/F-Agent-Dialogs/{date}-{feature-name}/{date}-{feature-name}-dialog.md`
+
+Read the dialog file first to understand:
+- Overall context and scope
+- What steps are complete
+- Current status and any blockers
+
+### Step File
+`docs/F-Agent-Dialogs/{date}-{feature-name}/steps/{N}-{step-name}.md`
+
+### Instructions
+1. Read the dialog file completely
+2. Read the step file
+3. Execute the implementation
+4. Document decisions in the dialog BEFORE implementing
+5. Verify against acceptance criteria
+6. Update dialog file: step status → ✅, add Progress Log entry
+```
+</action>
+
+### Track Progress
+
+<ask>**Step {N} — What's the status?**
+
+[A] ✅ Complete — Move to next step
+[B] 🔄 In Progress — Still working
+[C] ⏸️ Blocked — Cannot proceed
+[D] ❌ Skip — Will not implement
+
+Status:</ask>
+
+<action>Update dialog file with reported status</action>
+
+---
+
+## HANDLING ISSUES
+
+### If Implementation Differs from Spec
+
+<action>
+Document in the dialog file's "Spec Changes Discovered" section:
+
+| Issue | Resolution | Spec Updated? |
+|-------|------------|---------------|
+| {issue} | {how resolved} | 🔲 |
+</action>
+
+### If Step is Too Complex
+
+<action>
+Options:
+1. Break into sub-steps (create additional step files)
+2. Simplify scope (update dialog file)
+3. Seek clarification (document blocker)
+</action>
+
+### If Blocked on Dependencies
+
+<action>
+1. Update step status: ⏸️ Blocked
+2. Document the blocker in Notes
+3. Move to next step if possible
+4. Return to blocked step later
+</action>
+
+---
+
+## PROGRESS TRACKING
+
+### After Each Step
+
+<action>
+Update the Steps Overview table:
+
+| # | Step | Status | Notes |
+|---|------|--------|-------|
+| 1 | Step name | ✅ | Completed |
+| 2 | Step name | ✅ | Completed with minor changes |
+| 3 | Step name | 🔄 | In progress |
+| 4 | Step name | 🔲 | Not started |
+</action>
+
+### Progress Log Entry
+
+<action>
+Add to Progress Log:
+
+```markdown
+### {YYYY-MM-DD}
+- Completed Step 1: {description}
+- Completed Step 2: {description}
+- Started Step 3
+- Discovered: {any issues or learnings}
+```
+</action>
+
+---
+
+## ALL STEPS COMPLETE
+
+<check if="all_steps_complete">
+  <output>
+  **All steps complete!**
+
+  Proceed to Step 5 to finalize the dialog.
+
+  [A] Continue to Step 5: Complete Dialog
+  [B] Review the implementation first
+
+  Choice:
+  </output>
+</check>
+
+---
+
+## ROUTING
+
+<action>
+Based on completion:
+- All steps done → Load step-05-complete-dialog.md
+- Steps remaining → Continue execution loop
+- User pauses → Save state and exit
+</action>
+
+---
+
+_Agent Dialog Workflow — Step 4: Execute Steps_