asc/walkup
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add repo docs for agent guidance

Browse Source
This commit is contained in:
Codex
2026-04-22 09:50:11 -05:00
parent 7f4a4beb5a
commit f8dee2b7e7
3 changed files with 141 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

104
AGENTS.md
View File

@@ -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. - Check whether there are existing tests, scripts, or conventions to follow.
- Do not assume missing context; infer from the codebase first. - 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 ## Implementation Guidance
- Match the style and structure already used in the repository. - 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. - 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. - Keep public APIs, file layouts, and naming stable unless the task calls for a change.
## Testing Expectations ## Testing Expectations
- Create or update tests for every non-trivial behavior change. - 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. - Prefer tests that prove user-visible or contract-level behavior.
- Run relevant tests frequently while working, not only at the end. - Run relevant tests frequently while working.
- After each meaningful code change, run the smallest test scope that gives fast feedback. - After each meaningful change, run the smallest test scope that gives fast feedback.
- Before finishing, run the most relevant broader verification available for the touched area. - Before finishing, run broader verification for the touched area.
- If a change is not practical to test automatically, state that clearly and explain the gap. - If a change cannot be tested automatically, state that clearly.
## Safety Rules ## Safety Rules
- Never overwrite or revert user changes unless explicitly asked. - 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. - 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 ## 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. - 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 Discipline
- Commit work in logical, reviewable increments rather than as one large batch. - Commit work in logical, reviewable increments.
- Prefer a commit after each completed unit of work that passes relevant verification. - Prefer a commit after each completed unit of work that passes verification.
- Keep commits focused; avoid mixing unrelated changes. - Keep commits focused; avoid mixing unrelated changes.
- Use clear commit messages that describe the behavior or intent of the change. - Use clear commit messages describing behavior or intent.
- Do not commit broken work unless the user explicitly asks for a checkpoint commit. - Do not commit broken work unless explicitly requested.
## Branch Discipline ## Branch Discipline
- Do new feature work on a dedicated branch rather than directly on the main line. - Do new feature work on a dedicated branch.
- Use a distinct branch for each feature, fix, or clearly scoped task. - Use a distinct branch per feature, fix, or scoped task.
- Do not mix unrelated work on the same branch. - Start new work from `dev` unless specified otherwise.
- Start new work from `dev` unless the user specifies otherwise. - Keep branch names descriptive and scoped.
- Keep branch names descriptive and scoped to the task. - Do not carry unrelated uncommitted changes across branches.
- Before switching branches, check for uncommitted work and avoid carrying unrelated changes forward. - Merge completed feature branches into `dev` after verification.
- 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.
- Reserve `main` for release-ready code. - 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. - Keep purely agent-only working notes on the `ai` branch unless specified otherwise.
- Treat files such as `AGENTS.md`, `PLAN.md`, task notes, and other agent-only working documents as AI metadata rather than product code.
- Do not mix AI metadata commits with application feature commits. - Do not mix AI metadata commits with application feature commits.
- When updating AI metadata, switch to `ai` before editing or committing those files. - If a file is required for active repo guidance, keep it in the working branch.
- Keep the `ai` branch distinct from `dev` and `main` unless the user explicitly wants those files promoted.
## Agent Identity ## Agent Identity
- Use a dedicated Git author identity for AI-created commits instead of the user's personal identity. - Use a dedicated Git author identity for AI-created commits.
- Set the Git author name for agent work to `Codex`. - Default agent identity:
- Set the Git author email for agent work to `codex@local`. - Name: `Codex`
- Prefer per-commit identity flags such as `git -c user.name="Codex" -c user.email="codex@local" commit ...` instead of changing Git configuration. - Email: `codex@local`
- If explicit author metadata is needed, use `--author="Codex <codex@local>"`. - Prefer per-commit identity flags:
- Do not change the user's global Git identity for agent work. - `git -c user.name="Codex" -c user.email="codex@local" commit ...`
- Do not rely on inherited global Git identity for AI-authored commits. - 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 ## Release And Versioning
- Treat `dev` as the active integration branch for ongoing work. - Treat `dev` as the active integration branch.
- Merge `dev` into `main` only when preparing a release. - Merge `dev` into `main` only for releases.
- Bump the project version only as part of release preparation unless the user asks otherwise. - Bump versions only during release preparation unless instructed otherwise.
- Keep version changes in a dedicated release commit or tightly grouped release branch work. - Keep version changes grouped into release commits.
- Tag releases from `main` when the repository adopts a release process. - Tag releases from `main` when applicable.
## Communication ## Communication
- Be concise and concrete. - Be concise and concrete.
- Summarize what changed, why it changed, and how it was verified. - Summarize what changed, why, and how it was verified.
- Surface risks, tradeoffs, and follow-up work plainly. - Surface risks, tradeoffs, and follow-up work clearly.
## Scope ## Scope
- This file is intentionally general. - 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.

38
docs/architecture.md Normal file
View File

@@ -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.

42
docs/coding-standards.md Normal file
View File

@@ -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 <codex@local>` 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.