whiteport-design-studio 0.2.2 → 0.3.0

package/docs/learn/module-14-agentic-development/lesson-05-git-discipline.md

@@ -0,0 +1,349 @@
+# Module 14: Agentic Development
+
+## Lesson 5: Git Discipline
+
+**Keeping your work safe, organized, and shareable**
+
+---
+
+## Why Git Matters
+
+Every piece of code you create with an agent should be version controlled. Git is the safety net that lets you experiment without fear. If something breaks, you can go back. If you want to try a different approach, you can branch off. If you're ready to share, you can publish.
+
+Without Git, one bad agent session can wipe out hours of work. With Git, you can always undo.
+
+---
+
+## When to Use What
+
+Not every situation needs the full Git ceremony. It depends on where you are in the project and whether you're working alone or with a team.
+
+### Working alone, early in the project
+
+When you're the only designer and you're still writing specifications, exploring concepts, and building early prototypes — **working directly on main is fine.**
+
+Specifications are documents. They change constantly in early phases. Creating branches for every spec edit adds friction without adding value. Commit your work to main, push regularly, and move fast.
+
+```
+git add .
+git commit -m "Add signup form specification and prototype"
+git push
+```
+
+This is simple and effective. You have a history of everything you've done, and you can undo anything.
+
+### Working on code that matters
+
+As soon as you're building executable code, features, or anything that could break an existing project — **use branches.**
+
+Branches protect the stable version of your project. Your experiments happen in isolation. When they work, you merge them in. When they don't, you throw them away. No harm done.
+
+### Working with others
+
+When anyone else touches the same codebase — **always use branches and pull requests.**
+
+This isn't optional. It's how teams avoid overwriting each other's work.
+
+---
+
+## Let the Agent Handle Git
+
+You don't have to type Git commands yourself. The agent can create branches, make commits, and even create pull requests as part of the Design Log flow.
+
+**Tell the agent at the start:**
+
+> "Create a branch for this work. Commit after each completed step. When we're done, create a pull request."
+
+The agent will:
+1. Create a branch with a descriptive name
+2. Commit after each step with a clear message
+3. Push the branch when you say so
+4. Create a PR with a summary when you're ready
+
+**Trade-off:** You have less manual control over exactly what gets committed and when. But for most design work, this is perfectly acceptable. The convenience outweighs the loss of control.
+
+**When to take back control:** If you're working in a shared codebase or production project, review what the agent commits before pushing. A quick `git status` and `git diff` before each push keeps you informed.
+
+---
+
+## The Complete Process (Step by Step)
+
+For when you need to understand what's happening — or when you want to handle Git yourself.
+
+### Step 1: Check where you are
+
+```
+git status
+```
+
+This shows which branch you're on and if there are any changes.
+
+```
+On branch main
+nothing to commit, working tree clean
+```
+
+### Step 2: Get the latest version
+
+```
+git pull
+```
+
+This downloads any changes others have pushed. Always do this before starting new work.
+
+### Step 3: Create a branch
+
+```
+git checkout -b feature/signup-form-prototype
+```
+
+You've created a new branch and switched to it. All your work happens here.
+
+**Naming tips:**
+- `feature/signup-form` — building something new
+- `fix/mobile-navigation` — fixing a problem
+- `explore/dashboard-layout` — trying an idea
+
+### Step 4: Work and save as you go
+
+After each completed step in your Design Log, commit:
+
+```
+git add .
+git commit -m "Add signup form layout with all fields from spec"
+```
+
+**How often:** After every completed step. Step 1 done? Commit. Step 2 done? Commit. These are your save points.
+
+**Good commit messages:**
+- "Add form layout with all fields from spec"
+- "Style signup form with design tokens"
+- "Add blur-based validation for email and password"
+
+**Bad commit messages:**
+- "update"
+- "stuff"
+- "wip"
+
+### Step 5: Push your branch
+
+```
+git push -u origin feature/signup-form-prototype
+```
+
+Your branch now exists online. Others can see it. After the first push, just type `git push`.
+
+**When to push:**
+- End of a work session (backup)
+- When you want feedback
+- Before creating a pull request
+
+### Step 6: Create a pull request
+
+When you're done and the Design Log shows all tests passing:
+
+**Using the command line:**
+```
+gh pr create --title "Add signup form prototype" --body "Built from spec P02. See Design Log for details."
+```
+
+**Using GitHub:** Go to your repository, click "Pull requests", click "New pull request", select your branch.
+
+**What goes in the PR:**
+- What you built (reference the spec)
+- What to look for in review
+- Link to the Design Log
+- Any known limitations
+
+### Step 7: Merge and clean up
+
+When approved, merge the PR on GitHub. Then locally:
+
+```
+git checkout main
+git pull
+git branch -d feature/signup-form-prototype
+```
+
+You're back on main with your changes included.
+
+---
+
+## Working with Your Team
+
+### Roles in the codebase
+
+In a WDS team, different people touch the codebase in different ways:
+
+| Role | What they do in the repo |
+|---|---|
+| **Designer (you)** | Write specifications, create prototypes, build visual designs |
+| **Developer** | Build production features, set up infrastructure, review code |
+| **Product owner** | Review specifications and prototypes, approve PRs |
+
+### Communicating through Git
+
+Git isn't just version control — it's communication.
+
+**Your commit messages** tell the team what changed:
+> "Add error states to signup form per spec P02 section 4"
+
+**Your PR descriptions** give reviewers context:
+> "This implements the signup form prototype. All states from the spec are present. Validation triggers on blur. Touch targets verified at 48px."
+
+**Your branch names** show what's being worked on:
+> `feature/signup-form-prototype` tells everyone at a glance what this branch is about.
+
+### Avoiding conflicts
+
+Conflicts happen when two people change the same file at the same time. To minimize them:
+
+- **Communicate** — let the team know what you're working on
+- **Keep branches short-lived** — merge frequently, don't let branches sit for weeks
+- **Pull before you push** — always get the latest changes before pushing yours
+- **Stay in your lane** — work on the files related to your task, not random cleanups
+
+### When conflicts happen anyway
+
+```
+git pull origin main
+```
+
+Git marks the conflicts in your files:
+
+```
+<<<<<<< HEAD
+Your version
+=======
+Their version
+>>>>>>> main
+```
+
+**What to do:**
+1. Open the file
+2. Decide which version to keep (or combine both)
+3. Delete the conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`)
+4. Save, stage, and commit
+
+**When to ask for help:** If the conflict is in code you don't understand, ask a developer. Show them the Design Log so they have context.
+
+### Code reviews
+
+When a developer reviews your PR, they might:
+
+- **Approve** — your work is merged
+- **Request changes** — they want adjustments
+- **Comment** — they have questions or suggestions
+
+Don't take change requests personally. Reviews improve code quality and catch issues you might miss. Make the changes on your branch, commit, push — the PR updates automatically.
+
+---
+
+## Connecting Git to the Design Log
+
+Your Design Log meta section should include the branch:
+
+```markdown
+## Meta
+- Date: 2026-02-10
+- Input: P02-signup-form.md
+- Agent: Freya
+- Branch: feature/signup-form-prototype
+- Status: In Progress
+```
+
+And your log should note commits:
+
+```markdown
+### Step 1: Form layout (completed)
+- Created semantic HTML form structure
+- All elements from spec present
+- Commit: "Add form layout with all fields from spec"
+```
+
+This way, if you need to go back to any step, you know exactly which commit to find.
+
+---
+
+## When Things Go Wrong
+
+### "I made changes on the wrong branch"
+
+If you haven't committed yet:
+
+```
+git stash
+git checkout feature/correct-branch
+git stash pop
+```
+
+This moves your uncommitted changes to the right branch.
+
+### "The agent broke something and I want to go back"
+
+Find the last good commit:
+
+```
+git log --oneline
+```
+
+Restore a specific file to that state:
+
+```
+git checkout e4f5g6h -- src/components/SignupForm.html
+```
+
+### "I want to undo the last commit"
+
+```
+git reset --soft HEAD~1
+```
+
+Removes the last commit but keeps all the changes in your files.
+
+---
+
+## Quick Reference Card
+
+| What you want to do | Command |
+|---|---|
+| Check which branch you're on | `git status` |
+| Switch to main | `git checkout main` |
+| Get latest changes | `git pull` |
+| Create a new branch | `git checkout -b feature/name` |
+| See what changed | `git status` |
+| Stage files | `git add .` |
+| Commit | `git commit -m "message"` |
+| Push to remote | `git push` |
+| See commit history | `git log --oneline` |
+| Undo last commit (keep changes) | `git reset --soft HEAD~1` |
+| Stash changes temporarily | `git stash` / `git stash pop` |
+| Delete a merged branch | `git branch -d branch-name` |
+
+---
+
+## The Golden Rules
+
+1. **Alone + specs = work on main.** Don't overcomplicate early phases.
+2. **Code that matters = use branches.** Protect the stable version.
+3. **Working with others = branches + PRs.** Always.
+4. **Commit after every step.** These are your save points.
+5. **Push at the end of every session.** Don't lose work.
+6. **Let the agent help.** It can handle Git for you in the dialog.
+7. **When in doubt, ask a developer.** They untangle Git faster than Google.
+
+---
+
+## What's Next
+
+In the tutorial, you'll run through a complete agentic development session — from creating the Design Log through evaluation, feedback, and handling a stuck moment.
+
+---
+
+**[Continue to Tutorial: Your First Agentic Session →](tutorial-14.md)**
+
+---
+
+[← Back to Lesson 4](lesson-04-working-with-code.md) | [Back to Module Overview](module-14-agentic-development-overview.md)
+
+*Part of Module 14: Agentic Development*

package/docs/learn/module-14-agentic-development/module-14-agentic-development-overview.md

@@ -0,0 +1,249 @@
+# Module 14: Agentic Development
+
+**Time: 60 min | Agent: Freya | Phase: Design-Build**
+
+---
+
+## What Is Agentic Development?
+
+Agentic development is every process where you use an AI agent to transform your ideas into coded form.
+
+It can produce:
+
+- **Concepts** — quick explorations to test an idea
+- **Proof of concepts** — does this approach work at all?
+- **Prototypes** — working versions to evaluate and refine
+- **Production code** — final implementation for delivery
+
+It works in both directions:
+
+- **Inspiration → Specification** — Ask the agent to suggest or dream up a component, section, page, scenario, or complete app. Use the output as input for your specifications.
+- **Specification → Code** — Feed the agent your specifications and generate working code that matches.
+
+Whether you're exploring possibilities or building the final product, the process is the same.
+
+---
+
+## The 7-Activity Menu
+
+Agentic development is **menu-driven**, not linear. When you enter Phase 5, you choose what you need:
+
+```
+[P] Prototyping           — Build throwaway prototypes to validate ideas
+[D] Development           — Write production code from approved specs
+[F] Bugfixing             — Systematically fix bugs in existing code
+[E] Evolution             — Add features to existing products
+[A] Analysis              — Investigate codebase, architecture, patterns
+[R] Reverse Engineering   — Capture existing product as WDS specifications
+[T] Acceptance Testing    — Verify implementation against specs
+```
+
+Each activity has its own workflow with dedicated steps. The core agentic loop (plan → execute → evaluate → update) applies to all of them — the context differs.
+
+---
+
+## The Design Log
+
+Every agentic development session starts with a **Design Log** — a structured document that organizes the work.
+
+Before writing a single line of code, the agent creates:
+
+1. **Scope** — What are we building?
+2. **Tasks** — What steps will get us there?
+3. **Requirements** — What constraints must we respect?
+4. **Test protocol** — How will we know it's right?
+
+This is your plan. It evolves as you work.
+
+---
+
+## The Agentic Development Loop
+
+```
+┌──────────────┐
+│ Create plan  │  ← Design Log: scope, tasks, requirements, tests
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐
+│ Execute step │  ← Build one thing
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐
+│   Evaluate   │  ← Does it match? What did we learn?
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐
+│ Update plan  │  ← Reprioritize, add, remove, shuffle
+└──────┬───────┘
+       │
+       └──────────► Next step
+```
+
+After each step, you re-evaluate the plan. Priorities shift. New tasks appear. Others become irrelevant. The plan is alive.
+
+---
+
+## The Agent Tests Its Own Work
+
+The evaluate step isn't just you looking at the screen. The agent actively verifies its own output.
+
+Using **Puppeteer MCP**, the agent opens a browser, navigates to the prototype, and checks the acceptance criteria — while you watch.
+
+```
+┌──────────────┐
+│ Execute step │  ← Agent builds the feature
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐
+│ Agent opens  │  ← Puppeteer navigates to the page
+│   browser    │
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐
+│ Agent checks │  ← Reads text, clicks buttons, checks states,
+│  criteria    │     verifies styling, takes screenshots
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐
+│ Agent reports│  ← "5 of 6 criteria pass. Error color mismatch."
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐
+│ You decide   │  ← Fix it? Update spec? Move on?
+└──────────────┘
+```
+
+The agent narrates what it finds:
+
+> "Opening signup form at localhost:3000/signup..."
+> "Headline says 'Start in 2 minutes' — matches spec. ✓"
+> "Clicking submit with empty fields..."
+> "Error message: 'Please enter a valid email' — matches spec. ✓"
+> "Error color is #EF4444 — spec says #DC2626. ✗ Mismatch."
+> "Submit button touch target: 48px — meets 44px minimum. ✓"
+
+**The agent handles the measurable criteria.** Does the text match? Is the touch target big enough? Does the error state trigger?
+
+**You handle the qualitative judgment.** Does the flow feel natural? Is the visual hierarchy right? Would a real user understand this?
+
+Together, nothing gets missed. Functional testing happens during development — not after.
+
+---
+
+## Everything Is Logged
+
+Every step is logged. Every action is noted. Every decision is recorded.
+
+This means you can **restart the conversation at any time**. New session? Load the dialog. The agent picks up where you left off.
+
+```
+docs/_progress/
+├── 00-design-log.md        ← Plan, status, backlog
+└── agent-experiences/
+    └── 2026-02-10-signup-form.md  ← Session insights
+```
+
+---
+
+## Who Does What?
+
+Freya handles all agentic development activities:
+
+| Agent | Activities | When to use |
+|-------|-----------|-------------|
+| **Freya** | All 7 activities: [P] Prototyping, [D] Development, [F] Bugfixing, [E] Evolution, [A] Analysis, [R] Reverse Engineering, [T] Acceptance Testing | Design exploration, implementation, bugfixing, evolution, analysis, reverse engineering, and acceptance testing. |
+
+The process is the same across all activities. The scope and context differ.
+
+---
+
+## What You'll Learn
+
+### Lesson 1: The Development Design Log
+
+How the process is organized. Creating plans, logging steps, structuring sessions so you can restart at any time.
+
+### Lesson 2: Evaluation and Feedback
+
+After each step: evaluate, reprioritize, shuffle. How to give effective feedback to AI agents and keep the work on track.
+
+### Lesson 3: When You Get Stuck
+
+Sometimes the agent makes change after change and can't find the problem. When to troubleshoot, when to pivot, and when to ask a developer for help.
+
+### Lesson 4: Choosing Your Code Format
+
+Output formats, technology stacks, component libraries, and how to choose between static prototypes and executable code.
+
+### Lesson 5: Git Discipline
+
+Keeping your work safe with version control. When to branch, how to commit, working with your team, and letting the agent handle Git for you.
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Jumping in without a plan | Start with Design Log every time |
+| Not logging steps | Everything gets logged, no exceptions |
+| Keeping a stale plan | Re-evaluate after every step |
+| Fighting the AI for too long | Know when to ask for help |
+| Building everything at once | One step at a time |
+
+---
+
+## Practice
+
+Pick one specification and run the full loop:
+
+1. Create a Design Log with scope, tasks, and test protocol
+2. Execute one step
+3. Evaluate the result
+4. Update the plan
+5. Repeat
+
+---
+
+## Lessons
+
+### [Lesson 1: The Development Design Log](lesson-01-iterative-building.md)
+How the process is organized
+
+### [Lesson 2: Evaluation and Feedback](lesson-02-documenting-decisions.md)
+Staying in control as the agent builds
+
+### [Lesson 3: When You Get Stuck](lesson-03-when-you-get-stuck.md)
+Because AI doesn't always get it right
+
+### [Lesson 4: Choosing Your Code Format](lesson-04-working-with-code.md)
+Understanding what the agent produces and which technology fits your needs
+
+### [Lesson 5: Git Discipline](lesson-05-git-discipline.md)
+Keeping your work safe, organized, and shareable
+
+---
+
+## Tutorial
+
+### [Tutorial 14: Your First Agentic Session](tutorial-14.md)
+Hands-on guide to running a complete agentic development loop
+
+---
+
+## Next Module
+
+**[Module 15: Visual Design →](../module-15-visual-design/module-15-visual-design-overview.md)**
+
+Add soul and visual polish to your prototypes.
+
+---
+
+*Part of the WDS Course: From Designer to Linchpin*