Initial commit: homelab infrastructure wiki

- Full Obsidian vault content
- Host configs (ice, grizzley, ubuntu, proxmox, truenas, panda, hyte)
- Media stack documentation
- Traefik HA setup
- Automation scripts
- Bachelor party planning

homelab/raw/articles/forge/reference/docs-plan-and-act-guide.md

@@ -0,0 +1,105 @@
+---
+type: agent-doc
+agent: ForgeCode
+source: https://forgecode.dev/docs/plan-and-act-guide/
+scraped: 2026-04-28T21:02:18.556037+00:00
+content_hash: 999a0353
+---
+# Plan First, Then Act
+
+One of the biggest mistakes developers make with AI coding tools is jumping straight into implementation. After analyzing thousands of successful AI-assisted development sessions, we've learned that the most productive workflow follows a simple pattern: Plan first, then act.
+
+ForgeCode makes this workflow smooth with two specialized agents designed to work together.
+
+## Meet Your AI Development Team​
+
+### Muse Agent: Your Strategic Planner​
+
+Muse operates in read-only mode, making it perfect for analysis and planning without touching your code:
+
+- Analyzes your codebase and identifies potential issues
+- Creates detailed implementation plans
+- Explores different solution approaches
+- Reviews code for security, performance, and architecture concerns
+
+When to use Muse:
+
+- Before making significant changes to critical systems
+- When you need to understand the scope and impact of a task
+- For architecture planning.
+- When working in unfamiliar codebases
+
+### ForgeCode Agent: Your Implementation Partner​
+
+ForgeCode has full read-write access and handles the actual implementation:
+
+- Modifies files and creates new code
+- Executes commands and runs tests
+- Implements the solutions from your plan
+- Provides real-time feedback as changes are made
+
+When to use ForgeCode:
+
+- After reviewing and approving a plan from Muse
+- For routine tasks you're confident about
+- When you want hands-off implementation
+- For quick fixes with proper version control
+
+## The Plan-and-Act Workflow​
+
+Here's how successful developers use both agents together:
+
+### 1. Start with Muse for Planning​
+
+Switch to Muse from your ZSH shell:
+
+```
+:muse
+```
+
+Ask Muse to create a detailed plan:
+
+```
+: Write a plan for adding rate limiting to our API. Include:- Which endpoints need protection- Storage mechanism for rate data- Error responses and status codes- Integration points with existing middlewareNow critique this plan. What did you miss?
+```
+
+### 2. Review and Refine the Plan​
+
+Muse will provide a structured plan and then critique it for gaps. Review this carefully - a good plan eliminates most of implementation confusion later.
+
+### 3. Switch to ForgeCode for Implementation​
+
+Switch back to ForgeCode:
+
+```
+:forge
+```
+
+Reference the plan and start implementation:
+
+```
+: Following the $(@rate-limiting-plan.md) we discussed, implement the Redis-based rate limiter for the /api/auth endpoints first in $(@src/auth).
+```
+
+### 4. Iterate as Needed​
+
+Switch back to Muse if you encounter complex decisions, then return to ForgeCode for continued implementation.
+
+## Why This Works​
+
+Planning prevents confusion: When AI understands the full scope upfront, it makes better implementation decisions and avoids getting lost halfway through.
+
+Separation of concerns: Muse focuses purely on analysis without the pressure to implement, leading to better strategic thinking.
+
+Safety first: Critical systems get proper review before any changes are made.
+
+Faster iteration: Once you have a solid plan, ForgeCode can implement quickly without constant back-and-forth.
+
+## Quick Tips for Success​
+
+- Be specific in your planning requests - include edge cases, error handling, and integration points
+- Commit frequently - clean git state makes it easier to track AI changes
+- Review everything - treat AI output like a junior developer's code
+- Avoid frequent agent switching - it causes context thrashing, hurts cache performance, and creates confusing context handoffs
+
+Remember: You're the architect, Muse is your strategic advisor, and Forge is your implementation partner. Use each for what they do best.