From ff98ac7ed91dcd5bfff316cfb43fc28eca5d65c8 Mon Sep 17 00:00:00 2001
From: bisco <bisco@younerd.org>
Date: Fri, 20 Mar 2026 19:08:45 +0100
Subject: [PATCH] docs: add phase 0 repository readme

---
 README.md | 135 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 134 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index ff1821b..71282bf 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,135 @@
-# hoopscout-v2
+# 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.