|
| 1 | +# Operational Guidelines |
| 2 | + |
| 3 | +## Session Start |
| 4 | + |
| 5 | +- **Always** read `tasks/lessons.md` at the beginning of each session before doing any work |
| 6 | +- Apply relevant lessons to the current task |
| 7 | + |
| 8 | +## Workflow Orchestration |
| 9 | + |
| 10 | +### 1. Plan Node Default |
| 11 | + |
| 12 | +- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions) |
| 13 | +- If something goes sideways, STOP and re-plan immediately - don't keep pushing |
| 14 | +- Use plan mode for verification steps, not just building |
| 15 | +- Write detailed specs upfront to reduce ambiguity |
| 16 | + |
| 17 | +### 2. Subagent Strategy |
| 18 | + |
| 19 | +- Use subagents liberally to keep main context window clean |
| 20 | +- Offload research, exploration, and parallel analysis to subagents |
| 21 | +- For complex problems, throw more compute at it via subagents |
| 22 | +- One tack per subagent for focused execution |
| 23 | + |
| 24 | +### 3. Self-Improvement Loop |
| 25 | + |
| 26 | +- **When to amend** `tasks/lessons.md`: whenever something turns out wrong — user correction, test failure, CI failure, code review feedback, or any other signal that a mistake was made |
| 27 | +- **How to amend**: add a bullet with (1) what went wrong, (2) the root cause, (3) a rule that prevents the same mistake |
| 28 | +- **Best practice for AI agents**: updating lessons is the primary way to persist learning across sessions; agents lack long-term memory, so `tasks/lessons.md` is the project-specific memory that reduces repeated mistakes |
| 29 | +- Write rules for yourself that prevent the same mistake |
| 30 | +- Ruthlessly iterate on these lessons until mistake rate drops |
| 31 | +- Review lessons at session start for relevant project |
| 32 | + |
| 33 | +### 4. Verification Before Done |
| 34 | + |
| 35 | +- Never mark a task complete without proving it works |
| 36 | +- **After every feature/story completion**: Use the `post-feature-qa` skill (`.agents/skills/post-feature-qa/`) — run the QA checklist, ensure tests cover edge cases and implementation aligns with the story, fix gaps before marking done |
| 37 | +- Diff behavior between main and your changes when relevant |
| 38 | +- Ask yourself: "Would a staff engineer approve this?" |
| 39 | +- Run tests, check logs, demonstrate correctness |
| 40 | + |
| 41 | +### 5. Demand Elegance (Balanced) |
| 42 | + |
| 43 | +- For non-trivial changes: pause and ask "is there a more elegant way?" |
| 44 | +- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution" |
| 45 | +- Skip this for simple, obvious fixes - don't over-engineer |
| 46 | +- Challenge your own work before presenting it |
| 47 | + |
| 48 | +### 6. Autonomous Bug Fixing |
| 49 | + |
| 50 | +- When given a bug report: just fix it. Don't ask for hand-holding |
| 51 | +- Point at logs, errors, failing tests - then resolve them |
| 52 | +- Zero context switching required from the user |
| 53 | +- Go fix failing CI tests without being told how |
| 54 | + |
| 55 | +## Task Management |
| 56 | + |
| 57 | +1. **Plan First**: Write plan to `tasks/todo.md` with checkable items |
| 58 | +2. **Verify Plan**: Check in before starting implementation |
| 59 | +3. **Track Progress**: Mark items complete as you go |
| 60 | +4. **Explain Changes**: High-level summary at each step |
| 61 | +5. **Document Results**: Add review section to `tasks/todo.md` |
| 62 | +6. **Capture Lessons**: Update `tasks/lessons.md` after corrections — see "When to amend" and "How to amend" in Self-Improvement Loop above |
| 63 | + |
| 64 | +## Skills |
| 65 | + |
| 66 | +- **post-feature-qa** (`.agents/skills/post-feature-qa/`) — Apply after every feature or story implementation. Act as senior QA: verify test coverage for all edge cases and story alignment; produce QA report; fix gaps before claiming complete. |
| 67 | +- **add-agent-target** (`.agents/skills/add-agent-target/`) — Use when adding support for a new AI agent target. Requires current official-doc research, full import/generate implementation, rich realistic fixtures, complete unit/integration/e2e coverage, docs updates, and final QA. |
| 68 | + |
| 69 | +## Core Principles |
| 70 | + |
| 71 | +- **Simplicity First**: Make every change as simple as possible. Impact minimal code. |
| 72 | +- **No Laziness**: Find root causes. No temporary fixes. Senior developer standards. |
| 73 | +- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs. |
| 74 | + |
| 75 | +## Project-Specific Rules |
| 76 | + |
| 77 | +- **TDD mandatory**: Write failing tests FIRST, then implement. No exceptions. |
| 78 | +- **Max file size**: 200 lines. Split by responsibility if larger. |
| 79 | +- **No classes unless stateful**: Prefer pure functions + types. |
| 80 | +- **No `any`**: Use `unknown` + narrowing. |
| 81 | +- **Config source of truth**: `.agentsmesh/` directory. Generated files are artifacts. |
| 82 | +- **Test naming**: `{module}.test.ts` colocated with source. Integration tests in `tests/integration/`. |
| 83 | +- **Generated artifact tests must be strict**: For generated file structures, assert exact file paths, exact file counts, and exact referenced wrapper/script sets. Do not use loose checks like "at least one file", broad `some(...)`, or prefix-only path assertions when the full output set is known. |
| 84 | +- **Commit format**: conventional commits — `feat|fix|test|refactor(scope): message` |
| 85 | +- **README must stay current**: Any change to CLI commands, flags, config schema, supported targets, or canonical file formats **must** be reflected in `README.md` before the task is marked complete. Treat the README as part of the API surface. |
| 86 | +- **Website docs must stay current**: Any change to CLI commands, flags, config schema, supported targets, canonical file formats, or other user-facing behavior **must** also be reflected in the documentation website (`website/src/content/docs/`). The website is the primary public documentation — treat it with the same rigor as `README.md`. |
| 87 | +- **Refer to PRD**: `docs/prd-v2-complete.md` for architecture decisions |
| 88 | +- **Refer to tasks**: `docs/agentsmesh-ai-first-tasks.md` for current task specs |
| 89 | + |
| 90 | +## AgentsMesh Generation Contract |
| 91 | + |
| 92 | +AgentsMesh is a config sync library for AI coding tools. The only canonical source of truth is the `.agentsmesh` directory at the project root; files emitted into target formats such as `AGENTS.md`, `.claude/`, `.cursor/`, `.junie/`, and similar directories are generated artifacts. When making changes, edit canonical config first, then regenerate and verify the target outputs. Preserve the library's bidirectional contract: import native tool config into canonical form, generate back to target-specific layouts, and keep projected or embedded features round-trippable rather than treating them as plain text exports. |
0 commit comments