Merge pull request #1035 from atxtechbro/feature/procedures-audit

refactor(procedures): Audit and restructure for actual workflow clarity

Author: atxtechbro

knowledge/procedures/README.md

@@ -2,12 +2,37 @@
 
 Actionable processes and workflows that evolve with experience.
 
-- `configuration-as-data.md` - Prefer declarative JSON over imperative scripts
-- `fs-write-full-paths.md` - Always use absolute paths in fs_write operations
-- `git-workflow.md` - Git conventions and branch management
+## 🎯 Core Workflow
+
+**Start here**: Our work follows a mechanical flow from issue to value delivery.
+
+### [Issue-to-PR Workflow](issue-to-pr-workflow.md)
+The complete flow: `GitHub Issue → Planning Mode → Implementation → Pull Request → Review → Merge`
+
+This is THE workflow. Everything else supports this core process.
+
+## Supporting Workflows
+
+### Active Development
+- `tmux-git-worktrees-claude-code.md` - The 100x productivity system with planning mode
+- `git-workflow.md` - Git conventions and branch management  
+- `worktree-workflow.md` - Git worktree isolation for parallel development
+- `slash-command-generation.md` - How slash commands like `/close-issue` work
+
+### Quality & Improvement
 - `post-pr-mini-retro.md` - Systems improvement retro after feature PRs
-- `see-also-pattern.md` - Bidirectional linking between related concepts
-- `worktree-workflow.md` - Git worktree workflow (beta/imperfect system)
+- `five-focusing-steps.md` - Identify and optimize constraints
+
+### Conventions & Standards
+- `coding-conventions.md` - File paths, Python tools, and other learned patterns
+- `configuration-as-code.md` - Prefer declarative JSON over imperative scripts
+
+### Tool Integration
+- `mcp-client-integration.md` - Adding new MCP clients to the ecosystem
+- `mcp-tool-logging.md` - MCP server tool-level logging
+- `mcp-protocol-smoke-test.md` - Testing MCP protocol directly
+- `mcp-prompts.md` - Adding prompts to MCP servers
 
-## Future Procedure Ideas
-- **Self-organizing README**: Automate README.md reorganization based on git log activity patterns (daily GitHub Action analyzing last 1000 commits)
+### Tips & Setup
+- `agent-permission-setup.md` - Configure tool permissions for agents
+- `claude-code-tips.md` - Tips and shortcuts for Claude Code

knowledge/procedures/coding-conventions.md

@@ -0,0 +1,36 @@
+# Coding Conventions
+
+Small but important conventions learned through experience. These prevent common errors and ensure consistency.
+
+## File Operations
+
+### Always Use Absolute Paths
+**Rule**: Use `/full/path` or `~/path` - never relative paths like `./file`
+
+This prevents path resolution errors, especially with tools like fs_write.
+
+**Validation from Anthropic**: "We found that the model would make mistakes with tools using relative filepaths after the agent had moved out of the root directory. To fix this, we changed the tool to always require absolute filepaths—and we found that the model used this method flawlessly." ([Source](https://www.anthropic.com/engineering/building-effective-agents))
+
+## Python Development
+
+### Use UV for Package Management
+Use `uv` instead of `pip` for all Python packaging operations:
+- `uv pip install package` instead of `pip install package`
+- Modern, fast, and consistent with current best practices
+
+## Configuration
+
+### Prefer Data Over Code
+When configuring tools, prefer declarative JSON/YAML over imperative scripts. See [configuration-as-code](configuration-as-code.md) for detailed patterns.
+
+## Git Operations
+
+### Use MCP Git Tools
+Always use `mcp__git__*` tools instead of bash git commands:
+- Better error handling
+- Consistent interface
+- Proper path resolution
+
+## These Are Living Conventions
+
+This list grows as we learn. When you discover a pattern that prevents errors or improves consistency, add it here with a brief explanation of why it matters.

knowledge/procedures/ears-requirements.md

@@ -0,0 +1,105 @@
+# Issue-to-PR Workflow
+
+The mechanical workflow that delivers value: from GitHub issue to merged pull request.
+
+## The Complete Flow
+
+```
+GitHub Issue → Planning Mode → Implementation → Pull Request → Review → Merge
+```
+
+## Step-by-Step Mechanics
+
+### 1. GitHub Issue Defines the Work
+
+Every task starts as a GitHub issue:
+- Clear problem statement  
+- Success criteria defined
+- Labels automatically assigned by Claude Code GitHub Action based on principles
+
+**Anti-pattern**: Starting work without an issue leads to scope creep and unclear PRs.
+
+### 2. Planning Mode Review
+
+Run `/close-issue <number>` with planning mode (default):
+- Claude analyzes the issue
+- Presents a plan for review
+- You approve, refine, or reject
+
+**Key insight**: This shifts you from "driving" to "managing" - you review plans, not implementation details.
+
+### 3. Implementation in Isolation
+
+Once plan is approved:
+- Automatic worktree creation for complete isolation
+- Claude implements in focused sessions
+- Each commit represents verified progress
+
+**Tools involved**:
+- [Git worktrees](worktree-workflow.md) for isolation
+- [Git workflow](git-workflow.md) for commits
+- MCP tools for file operations
+
+### 4. Pull Request Packages the Solution
+
+Implementation complete:
+- Push branch to remote
+- Create PR referencing "Closes #<issue>"
+- PR description explains the solution
+
+**Quality gates**:
+- Small, focused changes (planning mode enables this)
+- Clear connection to original issue
+- Tests pass, linting clean
+
+### 5. Review Completes the Cycle
+
+PR review happens at the right altitude:
+- Review the solution, not individual lines
+- Verify it solves the original issue
+- Merge when approved
+
+### 6. Post-Merge Workflow
+
+After merging via GitHub UI:
+1. Exit Claude Code
+2. `git checkout main`
+3. `git pull origin main`
+4. `source setup.sh`
+5. Start new terminal session
+6. Restart Claude Code:
+   - Resume last chat for context continuity
+   - Or start fresh for new work
+
+**Note**: This manual process ensures clean environment and updated configurations.
+
+### 7. Optional: Post-PR Retro
+
+For significant work:
+- Run [post-PR mini retro](post-pr-mini-retro.md)
+- Capture learnings
+- Update procedures if needed
+
+## Why This Works
+
+1. **Clear boundaries**: Issues define WHAT, PRs deliver solutions
+2. **Parallel execution**: Multiple issues → multiple agents → multiple PRs
+3. **Quality through planning**: Better plans = better PRs
+4. **Reduced cognitive load**: Review plans and PRs, not live coding
+
+## Configuration
+
+Planning mode should be enabled by default for all users:
+```bash
+# In ~/.claude/settings.json
+{
+  "defaultMode": "plan"
+}
+```
+
+**Recommendation**: Add this to your `setup.sh` or dotfiles to ensure all team members start with planning mode enabled. This enforces OSE principles from day one.
+
+## Related
+
+- [tmux + git worktrees + Claude Code + Planning Mode](tmux-git-worktrees-claude-code.md) - The complete productivity system
+- [OSE Principle](../principles/ose.md) - Why this workflow embodies management over doing