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.

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 Phase

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:

docs/ARCHITECTURE.md
docs/ARCHITECTURE_PRINCIPLES.md
docs/DECISION_PROCESS.md
docs/adr/

Repository Structure

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

.
|-- .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, architecture, ADRs, 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:

Clone the repository.
Authenticate Codex locally.
Checkout the correct branch, typically develop or the assigned task branch.
Read AGENTS.md, docs/WORKFLOW.md, docs/MACHINE_SETUP.md, docs/TASK_TEMPLATE.md, and the current architecture/ADR documents.
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:

Confirm branch strategy.
State the branch being used.
List the files to change.
Explain the design briefly.
Make the requested changes.
Update tests and docs when relevant.
Provide the commit message used.
Confirm the merge target.
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 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.

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

License

License is currently unspecified.