|
| 1 | +# OpenWolf Operating Protocol |
| 2 | + |
| 3 | +You are working in an OpenWolf-managed project. These rules apply every turn. |
| 4 | + |
| 5 | +## File Navigation |
| 6 | + |
| 7 | +1. Check `.wolf/anatomy.md` BEFORE reading any file. It has a 2-3 line description and token estimate for every file in the project. |
| 8 | +2. If the description in anatomy.md is sufficient for your task, do NOT read the full file. |
| 9 | +3. If a file is not in anatomy.md, search with Grep/Glob, then update anatomy.md with the new entry. |
| 10 | + |
| 11 | +## Code Generation |
| 12 | + |
| 13 | +1. Before generating code, read `.wolf/cerebrum.md` and respect every entry. |
| 14 | +2. Check the `## Do-Not-Repeat` section — these are past mistakes that must not recur. |
| 15 | +3. Follow all conventions in `## Key Learnings` and `## User Preferences`. |
| 16 | + |
| 17 | +## After Actions |
| 18 | + |
| 19 | +1. After every significant action, append a one-line entry to `.wolf/memory.md`: |
| 20 | + `| HH:MM | description | file(s) | outcome | ~tokens |` |
| 21 | +2. After creating, deleting, or renaming files: update `.wolf/anatomy.md`. |
| 22 | + |
| 23 | +## Cerebrum Learning (MANDATORY — every session) |
| 24 | + |
| 25 | +OpenWolf's value comes from learning across sessions. You MUST update `.wolf/cerebrum.md` whenever you learn something useful. This is not optional. |
| 26 | + |
| 27 | +**Update `## User Preferences` when the user:** |
| 28 | +- Corrects your approach ("no, do it this way instead") |
| 29 | +- Expresses a style preference (naming, structure, formatting) |
| 30 | +- Shows a preferred workflow or tool choice |
| 31 | +- Rejects a suggestion — record what they preferred instead |
| 32 | +- Asks for more/less detail, verbosity, explanation |
| 33 | + |
| 34 | +**Update `## Key Learnings` when you discover:** |
| 35 | +- A project convention not obvious from the code (e.g., "tests go in __tests__/ not test/") |
| 36 | +- A framework-specific pattern this project uses |
| 37 | +- An API behavior that surprised you |
| 38 | +- A dependency quirk or version constraint |
| 39 | +- How modules connect or data flows through the system |
| 40 | + |
| 41 | +**Update `## Do-Not-Repeat` (with date) when:** |
| 42 | +- The user corrects a mistake you made |
| 43 | +- You try something that fails and find the right approach |
| 44 | +- You discover a gotcha that would trip up a fresh session |
| 45 | + |
| 46 | +**Update `## Decision Log` when:** |
| 47 | +- A significant architectural or technical choice is made |
| 48 | +- The user explains why they chose approach A over B |
| 49 | +- A trade-off is explicitly discussed |
| 50 | + |
| 51 | +**The bar is LOW.** If in doubt, add it. A cerebrum entry that's slightly redundant costs nothing. A missing entry means the next session repeats the same discovery process. |
| 52 | + |
| 53 | +## Bug Logging (MANDATORY) |
| 54 | + |
| 55 | +**Log a bug to `.wolf/buglog.json` whenever ANY of these happen:** |
| 56 | +- The user reports an error, bug, or problem |
| 57 | +- A test fails or a command produces an error |
| 58 | +- You fix something that was broken |
| 59 | +- You edit a file more than twice to get it right |
| 60 | +- An import, module, or dependency is missing or wrong |
| 61 | +- A runtime error, type error, or syntax error occurs |
| 62 | +- A build or lint command fails |
| 63 | +- A feature doesn't work as expected |
| 64 | +- You change error handling, try/catch blocks, or validation logic |
| 65 | +- The user says something "doesn't work", "is broken", or "shows wrong X" |
| 66 | + |
| 67 | +**Before fixing:** Read `.wolf/buglog.json` first — the fix may already be known. |
| 68 | + |
| 69 | +**After fixing:** ALWAYS append to `.wolf/buglog.json` with this structure: |
| 70 | +```json |
| 71 | +{ |
| 72 | + "id": "bug-NNN", |
| 73 | + "timestamp": "ISO date", |
| 74 | + "error_message": "exact error or user complaint", |
| 75 | + "file": "file that was fixed", |
| 76 | + "root_cause": "why it broke", |
| 77 | + "fix": "what you changed to fix it", |
| 78 | + "tags": ["relevant", "keywords"], |
| 79 | + "related_bugs": [], |
| 80 | + "occurrences": 1, |
| 81 | + "last_seen": "ISO date" |
| 82 | +} |
| 83 | +``` |
| 84 | + |
| 85 | +**The threshold is LOW.** When in doubt, log it. A false positive in the bug log costs nothing. A missed bug means repeating the same mistake later. |
| 86 | + |
| 87 | +## Token Discipline |
| 88 | + |
| 89 | +- Never re-read a file already read this session unless it was modified since. |
| 90 | +- Prefer anatomy.md descriptions over full file reads when possible. |
| 91 | +- Prefer targeted Grep over full file reads when searching for specific code. |
| 92 | +- If appending to a file, do not read the entire file first. |
| 93 | + |
| 94 | +## Design QC |
| 95 | + |
| 96 | +When the user asks you to check, evaluate, or improve the design/UI of their app: |
| 97 | + |
| 98 | +1. Run `openwolf designqc` via Bash to capture screenshots. |
| 99 | + - The command auto-detects a running dev server, or starts one from package.json if needed |
| 100 | + - Use `--url <url>` only if auto-detection fails |
| 101 | + - The command saves compressed JPEG screenshots to `.wolf/designqc-captures/` |
| 102 | + - Full pages are captured as sectioned viewport-height images (top, section2, ..., bottom) |
| 103 | +2. Read the captured screenshot images from `.wolf/designqc-captures/` using the Read tool. |
| 104 | +3. Evaluate the design against modern standards (Shadcn UI, Tailwind, clean React patterns): |
| 105 | + - Spacing and whitespace consistency |
| 106 | + - Typography hierarchy and readability |
| 107 | + - Color contrast and accessibility (WCAG) |
| 108 | + - Visual hierarchy and focal points |
| 109 | + - Component consistency |
| 110 | + - Whether the design looks "dull" or "white-coded" (generic, no personality) |
| 111 | +4. Provide specific, actionable feedback with fix suggestions. |
| 112 | +5. If the user approves, implement the fixes directly in their code. |
| 113 | +6. After fixes, re-run `openwolf designqc` to capture new screenshots and verify improvement. |
| 114 | + |
| 115 | +**Token awareness:** Each screenshot costs ~2500 tokens. The command compresses images (JPEG quality 70, max width 1200px) to minimize cost. For large apps, use `--routes / /specific-page` to limit captures. |
| 116 | + |
| 117 | +## Reframe — UI Framework Selection |
| 118 | + |
| 119 | +When the user asks to change, pick, migrate, or "reframe" their project's UI framework: |
| 120 | + |
| 121 | +1. Read `.wolf/reframe-frameworks.md` for the full framework knowledge base. |
| 122 | +2. Ask the user the decision questions from the file (current stack, priority, Tailwind usage, theme preference, app type). Stop early once the choice narrows to 1-2 options. |
| 123 | +3. Present a recommendation with reasoning based on the comparison matrix. |
| 124 | +4. Once the user confirms, use the selected framework's prompt from the file — **adapted to the actual project** using `.wolf/anatomy.md` for real file paths, routes, and components. |
| 125 | +5. Execute the migration: install dependencies, update config, refactor components. |
| 126 | +6. After migration, run `openwolf designqc` to verify the new look. |
| 127 | + |
| 128 | +**Do NOT read the entire reframe-frameworks.md into context upfront.** Read the decision questions and comparison matrix first (~50 lines). Only read the specific framework's prompt section after the user chooses. |
| 129 | + |
| 130 | +## Session End |
| 131 | + |
| 132 | +Before ending or when asked to wrap up: |
| 133 | + |
| 134 | +1. Write a session summary to `.wolf/memory.md`. |
| 135 | +2. Review the session: did you learn anything? Did the user correct you? Did you fix a bug? If yes, update `.wolf/cerebrum.md` and/or `.wolf/buglog.json`. |
0 commit comments