bisco/hoopscout-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: align top-level guidance with phase 1 baseline

Browse Source
This commit is contained in:
bisco
2026-03-20 20:06:23 +01:00
parent b58dff240c
commit 81834f3254
4 changed files with 64 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
README.md
View File

@ -1,18 +1,31 @@
# 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.
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 establish:
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
## Phase 0 Scope
## Current Phase
Phase 0 is focused on how work is done in this repository, not yet what gets built. The current scope includes:
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
@ -21,18 +34,15 @@ Phase 0 is focused on how work is done in this repository, not yet what gets bui
- machine setup guidance
- documentation discipline
Out of scope for now:
- application architecture
- domain model
- runtime topology
- ingestion strategy
- database choice
- feature set
- external integrations
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 in version control and portable across machines.
The repository is organized to keep durable workflow guidance and technical decision records in version control and portable across machines.
```text
.
@ -49,7 +59,7 @@ The repository is organized to keep durable workflow guidance in version control
- `.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.
- `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.
@ -91,7 +101,7 @@ 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`.
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
@ -114,20 +124,21 @@ Run `make doctor` as part of machine/bootstrap validation to confirm the reposit
## Current Status
The repository currently provides:
- repository bootstrap
- Codex/agent workflow foundation
- collaboration setup
- repository bootstrap and workflow foundation
- Codex/agent collaboration setup
- portable development baseline
- accepted phase-1 technical decisions for future implementation work
## After Phase 0
## Decision Baseline
Future technical decisions will be made explicitly in later phases once the workflow foundation is stable.
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