hoopscout-v2/README.md

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.

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