136 lines
3.7 KiB
Markdown
136 lines
3.7 KiB
Markdown
# 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`.
|
|
|
|
## 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` to perform the repository's local bootstrap and environment checks.
|
|
|
|
## 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.
|