Repo Operations

Repo operations

Day-to-day repository workflow. Hard coding rules: code-quality. VPS runners: runner-ops. CI YAML: github-actions. Entry contract: .agent/AGENTS.md. Personal taste: memory/personal/PREFERENCES.md. Stable facts: memory/semantic/DOMAIN_KNOWLEDGE.md.

Boundaries (Always / Ask / Never)

Always

• Run recall.py before deploy, migration, timestamp, debug, refactor
• Read extension-boundaries before providers, channels, tools, plugins, turn orchestration
• Read paw skill before using or changing the Paw CLI
• Run just sentrux when structure changes

Ask first

• Destructive or wide-scope work (schema drops, mass deletes, production config)
• git worktree create/remove, branch checkout/switch
• Bulk PR close/reopen > 5 PRs
• git stash create/apply/drop
• Force push

Never

• Commit secrets
• Backwards-compat shims or re-exports for old consumers
• Mix frontend/backend responsibilities

(See also memory/personal/PREFERENCES.md for personal Ask-before list.)

Quick reference

Beans issue tracker

Tasks live in .beans/pawrrtal-<id>--<slug>.md. Handbook: frontend/content/docs/handbook/agents/issue-tracker.md.

beans create "Short task title"
beans update <id> status in-progress
beans update <id> --body-file /tmp/body.md   # bulk body edits

Bean body style (junior-engineer actionable):

• ## Goal — one sentence
• ## Files — exact paths
• Numbered steps, tables for config, fenced blocks for every command/snippet
• Folder trees for new packages
• Epics: ## How it works + ## Rules block

ADRs: frontend/content/docs/handbook/decisions/. Domain context: frontend/content/docs/handbook/agents/domain.md.

Git and pull requests

• Small, review-friendly PRs; group related changes only
• Bulk close/reopen > 5 PRs → ask user with exact count first
• just commit / just push when using repo automation
• Fix lint warnings on every file the PR touches

See git-proxy skill for commit/push safety constraints.

Multi-agent safety

Other sessions may be editing in parallel.

• Do not git stash unless explicitly requested
• Do not create/remove git worktree or switch branches unless asked
• On commit → stage only your changes
• On push → git pull --rebase is OK; never discard others' work
• Unrecognized WIP files → ignore; mention only if relevant
• Formatting-only churn on files you already touched → auto-include in same commit when commit was requested

No pre-existing excuse

Never describe a failure as "pre-existing" to justify leaving it broken. Lint warnings, type errors, console errors, and flaky tests in files you touch get fixed. If scope explodes, open a sibling PR and reference it.

Rule file: .claude/rules/general/no-pre-existing-excuse.md.

How we work (nine rules)

Full text: .claude/rules/general/how-we-work-on-pawrrtal.md. Summary:

1. Read implementation before editing
2. Trace cause before fixing
3. Update DESIGN.md when tokens change in code
4. Reuse established patterns — no parallel mechanisms
5. cursor-pointer on interactive elements
6. Run toolchain after every file write
7. Ship tests with behavior changes
8. One concern per commit
9. Ask before destructive or scope-bending work

Architecture boundaries

Sentrux layers (.sentrux/rules.toml):

just sentrux    # local; CI posts PR comment on failure

Provider-agnostic tools:

• Tool implementations → backend/app/tools/
• Provider adapters → backend/app/providers/ (never import tools)
• Turn composition → backend/app/agents/tool_surface.py
• Enforced by scripts/check-no-tools-in-providers.py

Multi-file features → package directory with role-named modules (provider.py, Http.ts, Repo.ts); drop redundant prefixes. Template: backend/app/providers/gemini_cli/, frontend/features/<feature>/.

Semantic search first when CodeGraph/Serena/LSP is available; then rg. Rule: .claude/rules/general/prefer-semantic-code-search.md.

Check official docs and skills first

Before integrating a library:

• TanStack: npx @tanstack/intent@latest list / load <pkg>#<skill>
• Other libs: Context7 + DeepWiki MCPs (.mcp.json)
• Pawrrtal: .agent/skills/_index.md

Rule: .claude/rules/general/check-official-docs-and-skills-first.md.

UI and frontend guardrails (pointers)

Stagehand browser automation

MCP servers: stagehand-docs, context7, deepwiki (.cursor/mcp.json). Doc index: https://docs.stagehand.dev/llms.txt — fetch before asserting V3 APIs.

Cursor: .cursor/rules/stagehand-v3-typescript.mdc. Claude: .claude/rules/stagehand/.

Electron desktop (summary)

Frontend stays Electron-agnostic via frontend/lib/desktop.ts. New desktop features touch three files in lockstep: electron/src/preload.ts, electron/src/ipc.ts, frontend/lib/desktop.ts. IPC namespace desktop:*; renderer sandboxed.

Details: electron/README.md, workspace-context skill.

Related skills