From f8dee2b7e7192950635511195fad38964238e2c4 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 22 Apr 2026 09:50:11 -0500 Subject: [PATCH] Add repo docs for agent guidance --- AGENTS.md | 104 +++++++++++++++++++++++---------------- docs/architecture.md | 38 ++++++++++++++ docs/coding-standards.md | 42 ++++++++++++++++ 3 files changed, 141 insertions(+), 43 deletions(-) create mode 100644 docs/architecture.md create mode 100644 docs/coding-standards.md diff --git a/AGENTS.md b/AGENTS.md index 59e4ba7..6204c30 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,89 +18,107 @@ This file gives general operating guidance for coding agents working in this rep - Check whether there are existing tests, scripts, or conventions to follow. - Do not assume missing context; infer from the codebase first. +## Repo State Preflight + +- Before starting work, inspect `git status --short`. +- Treat pre-existing dirty files as user-owned by default. +- Do not include pre-existing user edits in agent commits unless explicitly approved. +- If requested work overlaps with user-owned uncommitted files, pause and ask how to proceed. +- Encourage the user to commit or stash their work before continuing when appropriate. + ## Implementation Guidance - Match the style and structure already used in the repository. -- Avoid broad refactors unless they are necessary to complete the task. +- Avoid broad refactors unless necessary to complete the task. - Add comments only where intent would otherwise be unclear. -- Prefer explicit, boring code over abstractions introduced too early. +- Prefer explicit, simple code over premature abstraction. - Keep public APIs, file layouts, and naming stable unless the task calls for a change. ## Testing Expectations - Create or update tests for every non-trivial behavior change. -- Prefer tests that prove the user-visible or contract-level behavior, not just implementation details. -- Run relevant tests frequently while working, not only at the end. -- After each meaningful code change, run the smallest test scope that gives fast feedback. -- Before finishing, run the most relevant broader verification available for the touched area. -- If a change is not practical to test automatically, state that clearly and explain the gap. +- Prefer tests that prove user-visible or contract-level behavior. +- Run relevant tests frequently while working. +- After each meaningful change, run the smallest test scope that gives fast feedback. +- Before finishing, run broader verification for the touched area. +- If a change cannot be tested automatically, state that clearly. ## Safety Rules - Never overwrite or revert user changes unless explicitly asked. -- Avoid destructive commands unless the user clearly requested them. +- Avoid destructive commands unless clearly requested. - Call out assumptions when they materially affect behavior. -- If you find unrelated problems, note them separately rather than folding them into the same change. +- If you find unrelated problems, note them separately. ## Verification -- Run the smallest relevant verification available after making changes. +- Run the smallest relevant verification after making changes. - If tests or checks cannot be run, say so explicitly. -- When possible, verify both the happy path and the most likely failure path. +- Verify both the happy path and the most likely failure path when possible. + +## Documentation + +- Re-read `AGENTS.md`, `PLAN.md`, and relevant files in `docs/` before planning or implementing. +- Update `docs/` when behavior, structure, or standards change. +- Update `PLAN.md` when work is completed, deferred, or split into follow-up work. +- Do not consider work complete until code and docs are aligned. ## Commit Discipline -- Commit work in logical, reviewable increments rather than as one large batch. -- Prefer a commit after each completed unit of work that passes relevant verification. +- Commit work in logical, reviewable increments. +- Prefer a commit after each completed unit of work that passes verification. - Keep commits focused; avoid mixing unrelated changes. -- Use clear commit messages that describe the behavior or intent of the change. -- Do not commit broken work unless the user explicitly asks for a checkpoint commit. +- Use clear commit messages describing behavior or intent. +- Do not commit broken work unless explicitly requested. ## Branch Discipline -- Do new feature work on a dedicated branch rather than directly on the main line. -- Use a distinct branch for each feature, fix, or clearly scoped task. -- Do not mix unrelated work on the same branch. -- Start new work from `dev` unless the user specifies otherwise. -- Keep branch names descriptive and scoped to the task. -- Before switching branches, check for uncommitted work and avoid carrying unrelated changes forward. -- If the current branch is not appropriate for the requested task, create or switch to a better-scoped branch before editing code. -- Merge completed feature branches into `dev` after relevant verification passes. +- Do new feature work on a dedicated branch. +- Use a distinct branch per feature, fix, or scoped task. +- Start new work from `dev` unless specified otherwise. +- Keep branch names descriptive and scoped. +- Do not carry unrelated uncommitted changes across branches. +- Merge completed feature branches into `dev` after verification. - Reserve `main` for release-ready code. -## AI Metadata Branch +## AI Metadata -- Keep AI coordination files on a dedicated `ai` branch unless the user specifies otherwise. -- Treat files such as `AGENTS.md`, `PLAN.md`, task notes, and other agent-only working documents as AI metadata rather than product code. +- Keep purely agent-only working notes on the `ai` branch unless specified otherwise. - Do not mix AI metadata commits with application feature commits. -- When updating AI metadata, switch to `ai` before editing or committing those files. -- Keep the `ai` branch distinct from `dev` and `main` unless the user explicitly wants those files promoted. +- If a file is required for active repo guidance, keep it in the working branch. ## Agent Identity -- Use a dedicated Git author identity for AI-created commits instead of the user's personal identity. -- Set the Git author name for agent work to `Codex`. -- Set the Git author email for agent work to `codex@local`. -- Prefer per-commit identity flags such as `git -c user.name="Codex" -c user.email="codex@local" commit ...` instead of changing Git configuration. -- If explicit author metadata is needed, use `--author="Codex "`. -- Do not change the user's global Git identity for agent work. -- Do not rely on inherited global Git identity for AI-authored commits. +- Use a dedicated Git author identity for AI-created commits. +- Default agent identity: + - Name: `Codex` + - Email: `codex@local` +- Prefer per-commit identity flags: + - `git -c user.name="Codex" -c user.email="codex@local" commit ...` +- Do not change the user's global Git identity. + +## Commit Ownership + +- The user and agents use separate Git identities. +- Only agent-authored changes should be included in agent commits. +- Do not include pre-existing user edits in agent commits unless explicitly approved. +- If overlap exists, pause and ask before proceeding. ## Release And Versioning -- Treat `dev` as the active integration branch for ongoing work. -- Merge `dev` into `main` only when preparing a release. -- Bump the project version only as part of release preparation unless the user asks otherwise. -- Keep version changes in a dedicated release commit or tightly grouped release branch work. -- Tag releases from `main` when the repository adopts a release process. +- Treat `dev` as the active integration branch. +- Merge `dev` into `main` only for releases. +- Bump versions only during release preparation unless instructed otherwise. +- Keep version changes grouped into release commits. +- Tag releases from `main` when applicable. ## Communication - Be concise and concrete. -- Summarize what changed, why it changed, and how it was verified. -- Surface risks, tradeoffs, and follow-up work plainly. +- Summarize what changed, why, and how it was verified. +- Surface risks, tradeoffs, and follow-up work clearly. ## Scope - This file is intentionally general. -- Add stack-specific or workflow-specific guidance here as the repository grows. +- Add stack-specific or workflow-specific guidance as the repository grows. \ No newline at end of file diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..aa3ac56 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,38 @@ +# Architecture + +Walkup is a baseball walk-up song app with a React PWA frontend and a FastAPI backend. + +## System Overview + +- The frontend runs as a browser app and PWA. +- The backend owns authentication, persisted app data, and media processing. +- TeamSnap is the source of truth for teams, members, events, lineups, and availability. +- The backend stores only app-owned data plus TeamSnap external IDs and tokens needed for the session flow. + +## Frontend + +- `frontend/` contains the React application. +- The app uses React Router for navigation and TanStack Query for server state. +- TeamSnap data is loaded through the official JavaScript SDK from the browser after the backend provides an access token. +- The UI includes player, operator, and library views for clip management and gameday playback. +- The app is shipped as a PWA with install and offline-prep behavior. + +## Backend + +- `backend/` contains the FastAPI application. +- The backend handles TeamSnap OAuth start, callback, and token refresh. +- It manages session state, clip metadata, game assignment state, and normalized media storage. +- Media files are stored locally in the backend storage path during development. + +## Data Boundaries + +- TeamSnap entities are not durably mirrored as first-class backend records. +- App-owned records include media assets, clips, playback assignments, and related metadata. +- Game-day clip pinning is modeled as app state that references TeamSnap game IDs and clip IDs. + +## Local Development + +- Docker Compose is the normal development path. +- The frontend is served separately through Vite in development. +- The backend is run through FastAPI with local storage and Docker secrets for TeamSnap credentials. +- `README.md` contains the setup steps and environment expectations. diff --git a/docs/coding-standards.md b/docs/coding-standards.md new file mode 100644 index 0000000..86c4227 --- /dev/null +++ b/docs/coding-standards.md @@ -0,0 +1,42 @@ +# Coding Standards + +These rules apply to Walkup-specific work in this repository. + +## General + +- Prefer the smallest change that fully solves the problem. +- Preserve existing behavior unless the task explicitly requires a change. +- Keep control flow straightforward and naming explicit. +- Avoid broad refactors unless they are necessary to complete the task. + +## Frontend + +- Match the existing Bootstrap-based UI patterns. +- Use Bootstrap Icons for iconography rather than custom SVG drawing. +- Keep interactive controls readable and compact, especially in menus and toolbars. +- Prefer UI changes that fit the current layout and spacing conventions. + +## Backend + +- Keep route handlers thin and push shared logic into helper functions when it improves clarity. +- Treat tests as part of the implementation for non-trivial behavior changes. +- Preserve API shape unless the change requires a contract update. + +## Testing + +- Add or update tests for user-visible behavior changes. +- Run the smallest useful verification first, then broader checks for the touched area. +- If a change cannot be covered automatically, call out the gap clearly. + +## Git And Workflow + +- Work on a dedicated branch for a scoped change. +- Use the `Codex ` identity for agent-authored commits. +- Keep commits focused and reviewable. +- Do not mix unrelated changes into the same commit. + +## Docs + +- Keep `docs/architecture.md` aligned with the current app structure. +- Keep `docs/coding-standards.md` aligned with actual repo practice. +- Update `PLAN.md` when work is completed, deferred, or split.