148 lines
4.4 KiB
Markdown
148 lines
4.4 KiB
Markdown
# 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.
|
|
|
|
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.
|
|
|
|
```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, 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:
|
|
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.
|
|
|
|
## 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.
|