# HoopScout v2

HoopScout v2 is currently in phase 0. This repository is being used to define a durable, repository-owned development workflow for Codex and custom agents before product architecture or application features are decided.

The current goal is to establish:
- Codex-assisted development
- custom agent usage
- repeatable task execution
- repository-owned instructions
- machine portability
- branch discipline

## Phase 0 Scope

Phase 0 is focused on how work is done in this repository, not yet what gets built. The current scope includes:
- repository workflow
- branch policy
- Codex project configuration
- agent roles
- reusable task-closeout behavior
- machine setup guidance
- documentation discipline

Out of scope for now:
- application architecture
- domain model
- runtime topology
- ingestion strategy
- database choice
- feature set
- external integrations

## Repository Structure

The repository is organized to keep durable workflow guidance in version control and portable across machines.

```text
.
|-- .codex/
|-- .agents/skills/
|-- docs/
|-- scripts/
|-- AGENTS.md
|-- Makefile
|-- README.md
|-- .editorconfig
`-- .gitignore
```

- `.codex/` stores repository-scoped Codex configuration and agent definitions.
- `.agents/skills/` stores reusable skills for repeatable repository workflows.
- `docs/` stores workflow, machine setup, and task execution guidance.
- `scripts/` stores repository utility scripts such as local checks.
- `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.

## Workflow

Protected branches:
- `main`
- `develop`

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.

## 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`, and `docs/TASK_TEMPLATE.md`.
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.

## Current Status

The repository currently provides:
- repository bootstrap
- Codex/agent workflow foundation
- collaboration setup
- portable development baseline

## After Phase 0

Future technical decisions will be made explicitly in later phases once the workflow foundation is stable.

## Contributing

To contribute in the current phase:
- read `AGENTS.md`
- read `docs/WORKFLOW.md`
- create a task branch from `develop`
- keep tasks narrowly scoped

## License

License is currently unspecified.