Skip to content

AGENTS.md

Latest commit

 

History

History
80 lines (74 loc) · 11.2 KB

AGENTS.md

File metadata and controls

80 lines (74 loc) · 11.2 KB
Raw

AGENTS

Working Style

  • Always run artisan/composer/npm commands through Sail (./vendor/bin/sail ...).
  • Doc-tree roles, canonical docs, strategy doc rules, checklist-depth separation, and CHANGELOG conventions all live in docs/DOC_ROLES.md. Read it when navigating docs or deciding where new content belongs.
  • Where dates are necessary in docs, use the date from the system you're running on.
  • No commits or pushes on Sundays; finished work waits in the tree until Monday.
  • Completed milestone/strategy docs get the x filename prefix in the same commit that closes them, with inbound links retargeted.
  • Check items off the moment they're done, in a commit; pending review/testing gets its own item instead of holding the checkoff. Notes stay tight: IDs, final wordings, verdicts.
  • After every commit, summarize what changed.
  • Prefer webhooks + queue redelivery over cron for convergence; schedule only what is genuinely time-triggered or has no push signal.
  • Milestone dates have one source of truth: docs/milestones.ics. PLAN.md's "Target" column must equal each milestone's .ics end date (DTEND). Every edit to an existing event must bump that event's SEQUENCE and refresh its DTSTAMP — subscribed calendars ignore changes without them. This invariant is guarded by tests/Feature/Docs/MilestoneScheduleConsistencyTest.php, tagged #[Group('local-only')] — it runs in the local suite (./vendor/bin/sail artisan test) but is excluded from the GitHub PR Tests gate, so run tests locally after any milestone-date change.
  • When adding features, update or create migrations + tests, then run ./vendor/bin/sail artisan test.
  • Also keep AGENTS.md updated to save on churn from session switching.
  • Keep .cybercreek/ local-only and untracked; do not commit agent coordination logs, local recovery files, or other local-only helper artifacts. For local-only work under .cybercreek/, follow .cybercreek/AGENTS_LOCAL.md if present.
  • The content site lives in its own repo, n8bar/cryptozing-site (split out in MS20.2); article work happens there, never in this repo.
  • Sail Compose includes a dedicated scheduler service that runs php artisan schedule:work; ./vendor/bin/sail up -d keeps the watcher alive automatically.
  • Specs come first: align on the requirement in the spec docs, implement, then update the docs to reflect what shipped; only reverse-engineer specs from existing code when we’ve explicitly agreed to do so.
  • Specs state desired behavior; implementation mechanics (webhooks, APIs, tooling) live in strategy docs and action items.
  • Docs are primarily internal architecture/engineering notes for us and future maintainers, not end-user documentation.
  • If the user is asking for your input/feedback (e.g. “what do you think?”, “should we…?”, “does this make sense?”), answer first and confirm before making changes—even if the request sounds actionable.
  • If asked to implement code before a spec exists, pause to confirm and recommend documenting the scope first (write the spec, then ship the code) unless the user explicitly insists otherwise.
  • If you create a new doc/spec that shapes future implementation scope, pause for user review before treating that doc as approved implementation direction.
  • If asked to merge a PR while there are uncommitted changes, unpushed commits, or any other local state that makes the tree non-clean or potentially misleading, pause and get explicit confirmation before merging.
  • Before any push/PR, keep all docs in sync: update specs first when scope shifts, then code, and ensure everything under docs/ (plus README links) reflects the same state in the same commit.
  • Whenever docs/** or AGENTS.md changes, commit/push those updates right away. Exception: single-item checklist checkoffs in the same active workstream do not need to be pushed right away and may be committed together later.
  • If the user has uncommitted doc edits in the same active workstream, preserve them and include them in the next related commit by default unless the user says otherwise.
  • Apply the UX guardrails in docs/UX_GUARDRAILS.md on every UX touch: Nielsen/WCAG as baseline; inline guidance, preserved input, no layout shift, focus/error handling, mobile/accessibility.
  • GitHub main is canonical. New work branches follow codex/<task>, and existing PRs must be updated via their original source branch rather than alternate branches.
  • PRs are gated by GitHub Actions PR Tests; keep branches current with origin/main before requesting review. Docs-only PRs (Markdown anywhere + docs/**, including milestones.ics) skip the suite via paths-ignore, so run milestone-date checks locally (the consistency test is local-only anyway).
  • Doc-only changes may be committed directly to main — no branch or PR required. "Doc-only" is the same carve-out as the PR gate: Markdown anywhere + docs/**, including milestones.ics. Anything touching code still goes through a codex/<task> (Claude: claude/<task>) branch + PR. Direct .ics commits bypass the PR entirely, so run milestone-date checks locally after any such change.
  • Small copy-only view tweaks don't need a PR — commit straight to main or let them ride another PR.

Do It List

  • The CryptoZing Initiative is the to-do list. The docs copy it. Rules: docs/DOC_ROLES.md.
  • Use the skill's CLI, not the MCP server: python3 .claude/skills/doitlist/scripts/doitlist.py <verb>. Source ~/.config/doitlist/cli.env and ~/.config/doitlist/mcp.env first.
  • The skill is a copy of /opt/DoItList/skills/doitlist/. Re-copy it; don't edit it here.

Multi-Agent Coordination

  • Primary and secondary agents are role-based, not capability-limited: secondaries can work docs, code, tests, or modules within their stated task.
  • Use subagents when the work can be split into independent, path-scoped tasks that materially reduce cycle time, especially for parallel code/doc/test updates or targeted read-only investigation.
  • Keep the critical path with the primary agent: do not delegate the next blocking step just to use a subagent; the primary agent owns integration, final verification, and the user-facing summary.
  • Assign each subagent a concrete deliverable plus clear file or module ownership; avoid overlapping write scopes, duplicated research, and broad "review the whole repo" style delegation.
  • Prefer subagents for bounded sidecar work such as spec/doc sync, isolated test fixes, narrow codebase exploration, or risk review of a specific area while the primary agent continues non-overlapping work.
  • Expect a dirty worktree during multi-agent sessions; do not stop for unrelated file changes outside your scoped paths.
  • Pause only when unexpected changes appear in the same file you need to edit, or when a destructive/revert action would be required.
  • Use path-scoped staging/commits (git add <paths>) so unrelated agent work is never swept into your commit.
  • Keep agent coordination logs local-only and untracked. If you use coordination artifacts under .cybercreek/ (for example Agents.comm), follow .cybercreek/AGENTS_LOCAL.md.
  • On checkin, leave a short handoff note: what changed, what remains, and any risks/tests to run.

Handy Commands

./vendor/bin/sail up -d
./vendor/bin/sail artisan test
./vendor/bin/sail artisan wallet:assign-invoice-addresses --dry-run
./vendor/bin/sail artisan wallet:check-config
./vendor/bin/sail artisan wallet:watch-payments

Environment Notes (Do these without having to be reminded)

  • docs/milestones/x21_OB_DEPLOYMENT.md is the closed record of the open-beta transition; docs/milestones/22_LINE_ITEMS_DEVELOPER_API.md is the active draft for line items and a polling-based developer API. The growth draft moves to M23, where outbound payment-event webhooks are a candidate for selection.
  • Wallet xpub onboarding lives at /wallet/settings; invoices expect a configured wallet or redirect there.
  • Data hygiene: As of 2025-11-16 the app only holds seed/test data—no real customers yet. Remove this note (and treat production emails accordingly) once live customer data exists.
  • CryptoZing must remain watch-only: never put private keys or seed phrases into tracked repo files, app config, database seeders, fixtures, tests, or normal application flows. If local testnet funding keys are needed for developer-only scenario setup, keep them only in untracked local storage (for example under .cybercreek/) and outside the product boundary.
  • MAIL_ALIAS_ENABLED/MAIL_ALIAS_DOMAIN can rewrite outbound recipients to the CryptoZing catch-all (mailer.cryptozing.app → Proton) for test scenarios; keep it disabled for open beta and any real-customer deployment.
  • Non-prod environments send through the same Mailgun account and sending domain as prod, so what gets exercised is the real transport. Containment is recipient aliasing, which rewrites every outbound recipient to the CryptoZing catch-all; it applies to all outbound mail, not to one send path. Because that containment is an app flag rather than a provider rule, MAIL_ALIAS_ENABLED=false on a non-prod box is the single change that lets it mail real people — treat it as such.
  • Non-prod MAIL_FROM_ADDRESS carries a mixed-case local part (No-RePlY@…) so a message's origin is readable at a glance. The domain stays lowercase: it is what DKIM signs and what the provider matches the From against. Keep prod's From lowercase.
  • SUPPORT_AGENT_EMAILS controls which accounts are treated as support accounts, and SUPPORT_ACCESS_HOURS should remain the fixed server-side expiration window for temporary owner-granted support access.
  • The CryptoZing.app domain is reserved solely for this project; feel free to provision DNS/subdomains/mail for app needs without saving it for other products.
  • Set APP_PUBLIC_URL to whatever domain should appear in public invoice links (localhost for dev, https://cryptozing.app for production) so emails never point at the wrong host.
  • Keep the Sail stack (./vendor/bin/sail up -d) running during active work/testing unless there’s a clear reason to tear it down.
  • Codex owns the terminal tooling: you drive Sail, git, and related commands—assume the user doesn’t have a shell open unless they say otherwise.
  • For .cybercreek/ changelog/findings handling, follow .cybercreek/AGENTS_LOCAL.md.
  • When you add or rename spec docs, update the README’s documentation section in the same commit so GitHub viewers always see the latest links.
  • Prod (the VPS) is driven only via one-shot ssh deploy@... '<command>' invocations — never a lingering remote shell; a bare terminal always means local/Sail.
  • Before any destructive command on either environment, read back WALLET_NETWORK, APP_PUBLIC_URL, and MAIL_ALIAS_ENABLED from the target's env and state which box it is.
  • Prod keeps APP_ENV=production so destructive artisan commands demand --force.

Roles

  • Special-invocation agent roles live under AgentRoles/ (e.g., Harvey for skeptical progress readouts).