Merge pull request #69 from MaxLinCode/claude/update-agents-and-skills-docs

Update AGENTS.md, CLAUDE.md, skills, and .dippy with workflow improve…

Author: MaxLinCode

.dippy

@@ -1,9 +1,6 @@
 # .dippy
 
 # Let normal read / inspect commands flow
-allow git status
-allow git diff
-allow git log
 allow ls
 allow pwd
 allow cat
@@ -13,12 +10,21 @@ allow rg
 allow find
 allow jq
 
+# allow git workflow
+allow git status
+allow git diff
+allow git log
+allow git add
+allow git add -p
+allow git commit
+allow git show
+allow git restore --staged
+
 # Let normal monorepo validation commands flow
 allow pnpm --filter * typecheck
 allow pnpm --filter * test
 allow pnpm --filter * lint
 allow pnpm biome *
-allow pnpm exec biome *
 allow pnpm tsc *
 allow pnpm vitest *
 allow pnpm jest *

AGENTS.md

@@ -1,10 +1,83 @@
-# AGENTS.md
+# Agent Instructions
+
+These instructions define the required search and discovery workflow.
+These rules take precedence over other exploration strategies.
+Always follow this protocol before reading multiple files or performing refactors.
+If you are about to search broadly or read many files, stop and apply this protocol first.
+
+## Global Priorities
+
+1. Minimize unnecessary file reads and token usage
+2. Follow the Search & Discovery Protocol before broad exploration
+3. Respect package ownership boundaries
+4. Prefer modifying existing modules over creating new ones
+
+## Search & Discovery Protocol
+
+1. File Discovery (fd)
+- Always start with fd
+- Prefer fd over `rg --files` for file enumeration
+- Never use find or ls -R
+- If results >200 files, refine
+- Example: fd -e ts auth
+
+
+2. Text Search (rg)
+- Use rg for literals and narrowing
+- Prefer -l / --files-with-matches first to identify target files
+- Use -S (smart-case) to avoid casing misses
+- Scope by extension when possible
+- If results >50 files, refine
+- Example: rg -S -t ts --files-with-matches "useAuth"
+
+3. Structural Search (sg)
+- Use sg for syntax-aware queries
+- Run after fd/rg narrowing
+- Remember that many TS functions are arrow functions; use broader patterns when needed
+- Examples:
+  - sg -p 'function $NAME($$$) { $$$ }'
+  - sg -p 'const $NAME = ($$$) => { $$$ }'
+
+4. Read Minimally
+- Prefer rg -n -C 3 over full file reads
+- Read order: config → entry → tests → impl
+
+5. Refactor Safety
+- Use fd to scope before large changes
+- Verify file count
+- Sample a few files first
+
+Power Pattern (bounded scan):
+fd -e ts . src/logic/ -x sg -p 'function $F($$$) { $$$ }'
+
+Note:
+- Use only when the directory is already narrow (<50 files)
+- This is a shortcut for function inventory, not for whole-repo scans
+- If unsure, run `fd` first to confirm file count
+
+## Codebase Map
+
+High-level module ownership:
+
+- `apps/web` — delivery surfaces (API routes, cron entrypoints, admin pages)
+- `packages/core` — product logic, planning behavior, schemas, scheduling rules
+- `packages/db` — persistence, repositories, database access
+- `packages/integrations` — external APIs and transport adapters
+- `docs/` — architecture, workflows, and decision records
+
+Navigation hints:
+
+- Start in `packages/core` for business logic questions
+- Start in `apps/web` for request/route entrypoints
+- Start in `packages/db` for data access or persistence issues
+- Start in `packages/integrations` for external API behavior
+- Check `docs/architecture.md` for system-level flows
 
 ## Mission
 
 Build Atlas as a production-quality, Telegram-first planning assistant. The codebase should stay understandable to a new contributor and safe for repeated agent-driven edits.
 
-## Architecture rules
+## Architecture Rules
 
 - `apps/web` owns delivery surfaces only: API routes, cron entrypoints, and internal admin pages.
 - Business logic belongs in `packages/*`, not in route handlers or page components.
@@ -13,37 +86,54 @@ Build Atlas as a production-quality, Telegram-first planning assistant. The code
 - `packages/db` implements persistence and repositories; do not spread SQL or ORM calls throughout the app.
 - `packages/integrations` owns external API clients and transport adapters, not product logic.
 
-## Anti-slop guardrails
+## Anti-Slop Guardrails
 
 - Prefer extending an existing module before creating a new abstraction.
 - Do not add a dependency without a short reason in the change summary.
 - No catch-all `utils` files unless the helpers are truly cross-cutting and cohesive.
 - Keep files focused. If a file starts spanning multiple responsibilities, split by behavior.
 - Keep comments rare and purposeful. Explain why, not what.
 
-## Testing rules
+## Testing Rules
 
 - Every core business rule or planning/scheduling heuristic should have a unit test.
 - Every webhook, reminder, or replanning bug fix requires an integration test.
 - Structured OpenAI outputs must be validated at the boundary and covered by contract tests.
 
-## Documentation rules
+## Documentation Rules
 
 - Update `README.md` when setup or core commands change.
 - Update `docs/architecture.md` when dependency direction or major flow changes.
 - When touching schemas, migrations, persisted records, ingestion record creation, or core data types, verify the change matches `docs/architecture/data-model-boundaries.md` and update that doc if the ownership model changes.
 - Add an ADR in `docs/decisions/` for meaningful infrastructure or architecture decisions.
 - Update `docs/current-work.md` when the active implementation focus changes.
 
-## Git workflow rules
+### Git Workflow Rules
+
+- Every workflow — no exceptions — must use a git worktree and a dedicated branch.
+  - Create a worktree before touching any files:
+    `git worktree add .worktrees/atlas-<short-description> -b claude/<short-description>`
+  - All edits, experiments, and commits must happen inside that worktree.
+  - Never modify files in the main checkout.
 
-- Follow `docs/workflows/feature-delivery.md` for product features, fixes, and behavior changes.
-- For any non-trivial code change, work on a feature branch named `codex/<short-description>`.
 - Do not commit or push implementation work directly to `main`.
-- Before pushing, confirm the current branch is not `main`.
-- If work is accidentally committed on `main`, move it to a feature branch before pushing.
+  - If work is accidentally committed on `main`, move it to a feature branch before pushing.
+
+- All changes must land via a dedicated branch.
+  - Prefer PR-based merges, even for small changes.
+  - Fast-forward merges from a clean branch are acceptable after work is complete.
+
+- Commit per logical change, not per file.
+- Stage only files related to the current change.
+- Write descriptive commit messages explaining the intent.
+
+- Follow `docs/workflows/feature-delivery.md` for product features, fixes, and behavior changes.
+
+- Clean up after completion:
+  - `git worktree remove .worktrees/atlas-<short-description>`
+  - `git branch -d claude/<short-description>` (if fully merged)
 
-## Execution rules
+## Execution Rules
 
 - Before finishing, run the narrowest relevant checks for the touched code.
 - For changes isolated to one package, prefer `pnpm --filter <package> typecheck` and `pnpm --filter <package> test`.
@@ -52,11 +142,11 @@ Build Atlas as a production-quality, Telegram-first planning assistant. The code
 - If dependencies, workspace config, Next.js config, or build tooling change, run `pnpm build`.
 - In the final response, summarize which checks ran and call out anything not verified.
 
-## Done definition
+## Done Definition
 
 A task is complete when:
 
 - the requested behavior exists,
 - affected checks pass,
 - docs are updated when setup, commands, or architecture changed,
-- and any skipped verification is clearly called out.
+- and any skipped verification is clearly called out.

CLAUDE.md

@@ -108,39 +108,30 @@ Build Atlas as a production-quality, Telegram-first planning assistant. The code
 - Add an ADR in `docs/decisions/` for meaningful infrastructure or architecture decisions.
 - Update `docs/current-work.md` when the active implementation focus changes.
 
-## Git Workflow Rules
+### Git Workflow Rules
 
-- **Every workflow — no exceptions — must use a git worktree and a dedicated branch.**
-  - Create a worktree before touching any files: `git worktree add .worktrees/atlas-<short-description> -b claude/<short-description>`
-  - All edits, experiments, and commits happen inside that worktree, never in the main checkout.
-  - This prevents dirty-worktree collisions between concurrent tasks (e.g. formatting runs vs. feature work).
-- Follow `docs/workflows/feature-delivery.md` for product features, fixes, and behavior changes.
-- Do not commit or push implementation work directly to `main`.
-- If work is accidentally committed on `main`, move it to a feature branch before pushing.
-
-- **Every workflow - no exceptions - must use a dedicated branch.**
-  - Create a branch before making changes:
-    git switch -c claude/<short-description>
-  - Do not perform implementation work directly on `main`.
+- Every workflow — no exceptions — must use a git worktree and a dedicated branch.
+  - Create a worktree before touching any files:
+    `git worktree add .worktrees/atlas-<short-description> -b claude/<short-description>`
+  - All edits, experiments, and commits must happen inside that worktree.
+  - Never modify files in the main checkout.
 
-- **Use a git worktree when work may run in parallel or overlap.**
-  - Examples: concurrent tasks, long-running edits, formatting passes, refactors, or agent-driven work.
-  - Create the worktree before touching files:
-    git worktree add .worktrees/atlas-<short-description> -b claude/<short-description>
-  - All edits and commits for that workflow must happen inside that worktree, never in the main checkout.
+- Do not commit or push implementation work directly to `main`.
+  - If work is accidentally committed on `main`, move it to a feature branch before pushing.
 
-- **Direct commits or merges to `main` are not allowed by default.**
-  - All changes must land via a dedicated branch.
+- All changes must land via a dedicated branch.
   - Prefer PR-based merges, even for small changes.
   - Fast-forward merges from a clean branch are acceptable after work is complete.
 
-- Follow `docs/workflows/feature-delivery.md` for product features, fixes, and behavior changes.
+- Commit per logical change, not per file.
+- Stage only files related to the current change.
+- Write descriptive commit messages explaining the intent.
 
-- If work is accidentally committed on `main`, move it to a feature branch before pushing.
+- Follow `docs/workflows/feature-delivery.md` for product features, fixes, and behavior changes.
 
-- Remove temporary worktrees after merge:
-  - git worktree remove .worktrees/atlas-<short-description>
-  - git branch -d claude/<short-description> (if fully merged)
+- Clean up after completion:
+  - `git worktree remove .worktrees/atlas-<short-description>`
+  - `git branch -d claude/<short-description>` (if fully merged)
 
 ## Execution Rules