@mohammadhprp/system-prompt 0.11.0 → 0.11.2

package/framework/skills/codenavi/references/coding-principles.md

@@ -0,0 +1,143 @@
+# Coding Principles
+
+Read this file during the Execute phase when implementing changes.
+These principles reduce common AI coding mistakes and ensure
+consistent, high-quality output.
+
+## 1. Think Before Coding
+
+Before writing any code:
+
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple approaches exist, present them with tradeoffs.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+- If the developer's approach seems wrong, say so constructively.
+  Don't be sycophantic — honesty prevents bugs.
+
+## 2. Simplicity First
+
+Write the minimum code that solves the problem.
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- No speculative optimization.
+- If you wrote 200 lines and it could be 50, rewrite it.
+
+The test: "Would a senior engineer say this is overcomplicated?"
+If yes, simplify.
+
+## 3. Surgical Changes
+
+When editing existing code:
+
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated issues, mention them — don't fix them.
+
+When your changes create orphans:
+
+- Remove imports, variables, and functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line traces directly to the mission objective.
+
+## 4. Goal-Driven Execution
+
+Transform vague tasks into verifiable goals:
+
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan with verification checkpoints.
+Strong success criteria enable autonomous execution. Weak criteria
+("make it work") require constant clarification — ask for better
+criteria rather than guessing.
+
+## 5. Respect the Codebase
+
+You are a guest in this codebase. Act like it.
+
+- Use the same naming conventions already in the project.
+- Use the same file organization patterns.
+- Use the same error handling approach.
+- Use the same import style (named vs default, relative vs absolute).
+- If the project uses semicolons, use semicolons. If it doesn't, don't.
+
+If existing conventions conflict with language best practices, flag it
+to the developer. Don't silently introduce a different convention.
+
+## 6. Language Best Practices
+
+Always follow the official best practices for the language and
+frameworks in use. This means:
+
+- Use idiomatic patterns for the language (e.g., list comprehensions
+  in Python, Optional chaining in TypeScript).
+- Follow the official style guide when the project doesn't have its own.
+- Use current, non-deprecated APIs and methods.
+- Handle errors according to the language's conventions (try/catch,
+  Result types, error returns — whatever the ecosystem prefers).
+
+Critical: Never rely on training memory for API signatures, method
+parameters, or framework behavior. Always verify against current
+documentation using the Knowledge Verification Chain:
+
+```
+.notebook/ → project docs → MCP Context7 → web search → flag as uncertain
+```
+
+## 7. Dependencies and Imports
+
+When adding new dependencies or imports:
+
+- Check if the project already has a dependency that solves the
+  problem before adding a new one.
+- Check the project's package manager and lockfile for existing
+  versions.
+- If adding a new dependency, mention it to the developer with
+  rationale — never silently add packages.
+- Match the project's import style and ordering conventions.
+
+## 8. Error Handling
+
+- Handle errors that can realistically occur.
+- Don't add catch blocks for theoretically impossible scenarios.
+- Use the project's existing error handling patterns.
+- Error messages should be actionable — tell what happened and
+  what to do about it, not just "Something went wrong."
+- Never swallow errors silently (empty catch blocks) unless
+  there's an explicit reason documented in a comment.
+
+## 9. Testing
+
+When tests are part of the mission:
+
+- Write tests that verify behavior, not implementation details.
+- Test the contract (input → output), not internal state.
+- Name tests descriptively: "should reject expired coupon"
+  not "test1" or "coupon test."
+- If modifying existing code, run existing tests first to
+  establish a baseline.
+- If adding a bug fix, write a test that reproduces the bug
+  first, then fix it.
+
+When tests are NOT part of the mission:
+
+- Don't add tests unless asked.
+- But DO mention if the change is risky and untested:
+  "This change affects the payment flow but there are no tests
+  covering this path. Consider adding tests for [specific cases]."
+
+## 10. Comments
+
+- Don't add comments that restate the code.
+- Don't remove existing comments unless they're provably wrong.
+- Add comments only for non-obvious business logic or workarounds.
+- If you add a workaround, explain WHY it's necessary and link
+  to the relevant issue/ticket if available.
+- Match the project's commenting style and language (human language).

package/framework/skills/codenavi/references/notebook-spec.md

@@ -0,0 +1,171 @@
+# .notebook/ Specification
+
+Read this file when you need to create or update notes during the
+Debrief phase, or when you need to understand the notebook format
+during Briefing.
+
+## Structure
+
+```
+.notebook/
+├── INDEX.md          # Always read first. Compact index of all notes.
+├── auth-flow.md      # Individual note files — flat by default.
+├── error-handling.md
+└── checkout-race.md
+```
+
+Notes start flat in the root of `.notebook/`. When volume exceeds
+~15 notes, organize into subdirectories by category:
+
+```
+.notebook/
+├── INDEX.md
+├── flows/
+│   ├── auth-flow.md
+│   └── checkout-flow.md
+├── patterns/
+│   └── error-handling.md
+├── gotchas/
+│   └── checkout-race.md
+└── domain/
+    └── coupon-types.md
+```
+
+Categories:
+
+- **flows** — How things work. Integrations, sequences, data paths.
+- **patterns** — How things are done here. Conventions, recurring structures.
+- **gotchas** — Traps. Bugs, quirks, counterintuitive behavior.
+- **domain** — Business concepts. Terminology, rules, logic not obvious in code.
+
+These categories are guidelines, not rigid rules. If a note fits
+multiple categories, pick the primary one. If none fits, put it in root.
+
+## INDEX.md Format
+
+The index must be compact. One line per note. The AI reads this every
+session, so every byte counts.
+
+```markdown
+# .notebook
+> Project intelligence — read before every mission
+
+Last updated: 2026-02-22
+
+- [auth-flow](auth-flow.md) — OAuth2 + refresh rotation | flow | auth, security
+- [error-handling](error-handling.md) — Error boundaries + custom hook | pattern | react, errors
+- [checkout-race](checkout-race.md) — Race condition on cart update | gotcha | checkout, cart
+- [coupon-types](coupon-types.md) — Percentage vs fixed vs BOGO rules | domain | coupons, pricing
+```
+
+Format per line:
+
+```
+- [slug](path) — summary (max ~80 chars) | category | tags
+```
+
+Rules for INDEX.md:
+
+- Keep summaries short and scannable.
+- Tags are lowercase, comma-separated. Use them for quick grep.
+- Update `Last updated` whenever the index changes.
+- If using subdirectories, paths include the folder: `flows/auth-flow.md`.
+- Sort by most recently updated, not alphabetically.
+
+## Individual Note Format
+
+Notes are telegraphic. Think field notes, not documentation.
+
+```markdown
+# Auth Flow
+> OAuth2 with refresh token rotation
+
+Entry: `src/middleware/auth.ts:authMiddleware()` (L12)
+Flow: middleware → `services/auth/jwt.ts:verify()` → `services/user/find.ts:findById()`
+
+Refresh: `services/auth/refresh.ts:rotateToken()`
+- Single-use tokens — consumed on refresh, new pair issued
+- Stored in Redis with TTL (see `lib/redis.ts:sessionStore`)
+
+OAuth providers: `config/oauth.ts` — Google, GitHub
+- Each provider maps to `services/auth/oauth/[provider].ts`
+
+Session: Redis-backed via `lib/redis.ts` (L45-62)
+
+Updated: 2026-02-22
+```
+
+### Format principles
+
+1. **Pointers, not copies.** Always reference as:
+   - `file/path.ts:functionName()` for functions
+   - `file/path.ts` (L10-25) for specific line ranges
+   - `file/path.ts:ClassName.method()` for class methods
+   Never paste code blocks into notes. Code changes; pointers
+   can be re-checked. Pasted code becomes stale lies.
+
+2. **One concept per note.** If it needs scrolling, split it.
+   A note about auth flow should not also cover session management
+   unless they're inseparable.
+
+3. **Minimal prose.** Use fragments, arrows, dashes. Not sentences.
+   "middleware → verify JWT → load user → attach to req" is better
+   than "The middleware first verifies the JWT token, then loads
+   the user from the database, and finally attaches it to the
+   request object."
+
+4. **Always include Entry point.** Every note should have a clear
+   starting point so the reader knows where to begin exploring.
+
+5. **Always include Updated date.** So the reader knows how fresh
+   the information is.
+
+6. **No opinions, only observations.** "Uses Redux for state" not
+   "Uses Redux instead of a better solution." If something is
+   genuinely problematic, state the observable impact:
+   "Redux store has 47 top-level keys — finding relevant state
+   requires searching across 12 reducers."
+
+## Creating the .notebook/ for the First Time
+
+When `.notebook/` doesn't exist yet:
+
+1. Create the directory.
+2. Create INDEX.md with the header only:
+
+   ```markdown
+   # .notebook
+   > Project intelligence — read before every mission
+
+   Last updated: [today]
+   ```
+
+3. Do NOT do a full project analysis. Notes are created organically
+   as you work. The first notes will come from your first mission's
+   Debrief.
+
+## Updating Notes
+
+When updating an existing note:
+
+1. Read the current content.
+2. Add, modify, or remove information based on what you discovered.
+3. Update the `Updated` date at the bottom.
+4. If the summary in INDEX.md changed, update it too.
+
+When information becomes invalid (e.g., a flow changed because of
+your work), update the note immediately — stale notes are worse
+than no notes.
+
+## Token Budget
+
+The entire `.notebook/` system is designed for progressive disclosure:
+
+- **INDEX.md** is read every session (~5-50 lines). Cost: minimal.
+- **Individual notes** are read only when relevant to the current
+  mission. The AI decides which to open based on INDEX.md tags.
+- **Total cost per session:** INDEX.md + 0-3 relevant notes.
+
+If INDEX.md grows beyond 50 entries, consider archiving old notes
+into an `archive/` subdirectory and removing them from the active
+index. Archived notes are still searchable but not loaded by default.