bisco/hoopscout-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add scouting shortlist mvp

Browse Source
This commit is contained in:
bisco
2026-04-07 17:29:55 +02:00
parent d1b5499a63
commit 99820419c4
10 changed files with 273 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files

159
README.md
View File

@ -1,40 +1,18 @@
# HoopScout v2
HoopScout v2 has completed its phase-0 workflow foundation and is now using accepted phase-1 decisions to guide implementation planning. The repository remains repository-owned, portable across machines, and explicit about how humans and Codex should work.
HoopScout v2 is a Django/PostgreSQL scouting application developed through a repository-first workflow. The repo keeps both implementation guidance and Codex collaboration rules in version control so the project stays portable across machines.
The current goal is to maintain:
- Codex-assisted development
- custom agent usage
- repeatable task execution
- repository-owned instructions
- machine portability
- branch discipline
- implementation guidance driven by accepted ADRs
## Current MVP
## Current Phase
The current application baseline provides:
- containerized local development
- curated sample seed data for manual exploration
- player scouting search with player, context, and stat filters
- matching season/team/competition context on search results
- result sorting and pagination
- a shared development shortlist for favorite players
Phase 0 established the working method for the repository. Phase 1 has already added accepted technical decisions for:
- architecture principles
- technical decision process
- runtime and development stack
- initial project structure
- containerized developer workflow
- configuration and environment strategy
Current work should follow those accepted decisions rather than re-deciding them informally.
## Workflow Foundation
The repository still depends on the phase-0 foundation for:
- repository workflow
- branch policy
- Codex project configuration
- agent roles
- reusable task-closeout behavior
- machine setup guidance
- documentation discipline
Key decision references:
Accepted technical and product-shaping decisions live in:
- `docs/ARCHITECTURE.md`
- `docs/ARCHITECTURE_PRINCIPLES.md`
- `docs/DECISION_PROCESS.md`
@ -42,121 +20,58 @@ Key decision references:
## Repository Structure
The repository is organized to keep durable workflow guidance and technical decision records in version control and portable across machines.
```text
.
|-- .codex/
|-- .agents/skills/
|-- app/
| |-- hoopscout/
| `-- scouting/
|-- docs/
|-- infra/
|-- requirements/
|-- scripts/
|-- tests/
|-- AGENTS.md
|-- Makefile
|-- README.md
|-- .editorconfig
`-- .gitignore
`-- README.md
```
- `.codex/` stores repository-scoped Codex configuration and agent definitions.
- `.agents/skills/` stores reusable skills for repeatable repository workflows.
- `app/` stores the Django project and scouting application code.
- `docs/` stores workflow, architecture, ADRs, machine setup, and task execution guidance.
- `infra/` stores local container and environment bootstrap files.
- `requirements/` stores the Python dependency baseline.
- `scripts/` stores repository utility scripts such as local checks.
- `tests/` stores repository-level testing notes and support files.
- `AGENTS.md` defines repository-wide agent behavior and task rules.
- `Makefile` exposes standard project commands.
- `README.md` introduces the repository and current phase.
- `.editorconfig` provides shared formatting defaults.
- `.gitignore` defines ignored files for the repository.
- `app/hoopscout/` contains the Django project settings and root URLs.
- `app/scouting/` contains the scouting domain models, views, templates, management commands, and tests tied to the app.
- `infra/` contains the local Docker Compose and image setup.
- `docs/` contains workflow and ADR documentation.
- `scripts/` contains repository checks such as `make doctor`.
## Local Development
1. Start the stack with `docker compose --env-file .env -f infra/docker-compose.yml up -d --build`.
2. Apply migrations with `docker compose --env-file .env -f infra/docker-compose.yml exec -T app python manage.py migrate`.
3. Load sample data with `docker compose --env-file .env -f infra/docker-compose.yml exec -T app python manage.py seed_scouting_data`.
4. Visit `http://127.0.0.1:8000/players/` to explore the scouting search MVP.
5. Use `http://127.0.0.1:8000/favorites/` to review the shared development shortlist.
## Workflow
Protected branches:
- `main`
- `develop`
- `main` is the stable branch.
- `develop` is the integration branch.
- normal work goes through `feature/*` branches created from `develop`.
- run `make doctor` before or during local setup to confirm the repository foundation is present.
Normal work goes through `feature/*` branches created from `develop`. Tasks should be completed on the task branch, committed there, and merged back into `develop` when done.
Durable project behavior belongs in the repository, especially:
- `AGENTS.md`
- `.codex/`
- `.agents/skills/`
- `docs/`
## Working with Codex
Durable project behavior should live in the repository so that work remains consistent across machines and contributors.
Repository-owned configuration examples:
- task workflow
- branch strategy
- coding process
- agent roles
- reusable skills
- machine setup instructions
- test and validation instructions
Local-only configuration examples:
- Codex authentication
- personal shell aliases
- editor preferences
- secrets and API keys
- machine-specific customizations not documented as shared examples
## New Machine Setup
When starting on a new machine:
1. Clone the repository.
2. Authenticate Codex locally.
3. Checkout the correct branch, typically `develop` or the assigned task branch.
4. Read `AGENTS.md`, `docs/WORKFLOW.md`, `docs/MACHINE_SETUP.md`, `docs/TASK_TEMPLATE.md`, and the current architecture/ADR documents.
5. Run `make doctor` to validate the local repository bootstrap before starting a task.
## Codex Task Style
Codex tasks in this repository should follow this order:
1. Confirm branch strategy.
2. State the branch being used.
3. List the files to change.
4. Explain the design briefly.
5. Make the requested changes.
6. Update tests and docs when relevant.
7. Provide the commit message used.
8. Confirm the merge target.
9. Stop.
## Local Checks
Run `make doctor` as part of machine/bootstrap validation to confirm the repository foundation is present and aligned.
## Development Bootstrap
For the current MVP baseline:
1. Start the local stack with `docker compose --env-file .env -f infra/docker-compose.yml up -d --build`.
2. Run `docker compose --env-file .env -f infra/docker-compose.yml exec -T app python manage.py migrate`.
3. Load sample scouting data with `docker compose --env-file .env -f infra/docker-compose.yml exec -T app python manage.py seed_scouting_data`.
4. Open `/players/` and use filters such as `PG + min assists` or `team + min TS%` to explore the seeded dataset.
## Current Status
The repository currently provides:
- repository bootstrap and workflow foundation
- Codex/agent collaboration setup
- portable development baseline
- accepted phase-1 technical decisions for future implementation work
## Decision Baseline
Future implementation work should follow the accepted ADR baseline unless a later ADR supersedes it.
Local-only responsibilities still include authentication, personal editor setup, shell aliases, and secrets.
## Contributing
To contribute in the current phase:
- read `AGENTS.md`
- read `docs/WORKFLOW.md`
- read the current ADR set in `docs/adr/`
- create a task branch from `develop`
- keep tasks narrowly scoped
- keep tasks narrowly scoped and aligned with accepted decisions
## License