From 81834f3254e631b8dce937c6ff35257e024cbfac Mon Sep 17 00:00:00 2001 From: bisco Date: Fri, 20 Mar 2026 20:06:23 +0100 Subject: [PATCH] docs: align top-level guidance with phase 1 baseline --- AGENTS.md | 36 +++++++++++++++++++------------- README.md | 51 ++++++++++++++++++++++++++++------------------ docs/PHASE_1.md | 2 ++ docs/adr/README.md | 12 ++++++++--- 4 files changed, 64 insertions(+), 37 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3b8dbda..8bc4d5d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,15 +2,20 @@ ## Scope of this repository -This repository is in **phase 0**. +Phase 0 is complete. -The goal of this phase is to define: +The repository now has: +- a completed workflow and portability foundation from phase 0 +- accepted phase-1 technical decisions recorded through ADRs +- enough documented guidance to support implementation work that follows the accepted baseline + +The goal of the current phase is to continue: - how development with Codex and custom agents works - how repository workflow works -- how tasks are executed and closed -- how the project remains portable across machines +- how technical decisions are documented and applied +- how implementation work follows accepted repository decisions -This phase is **not** for deciding the product architecture or implementing application features. +This repository is no longer limited to workflow/bootstrap work. Runtime, database, structure, workflow, and configuration baselines have already been accepted through ADRs and must guide future implementation tasks. Agents must optimize for: - repeatability @@ -170,6 +175,14 @@ Never claim tests passed unless they were actually executed. --- +## ADR Discipline + +Implementation work must follow accepted ADRs. + +Current accepted decisions live under `docs/adr/` and include the baseline runtime, structure, developer workflow, and configuration strategy. If a task depends on a new major technical choice, document or update the decision explicitly rather than relying on undocumented assumptions. + +--- + ## Documentation discipline Whenever behavior changes, update docs if relevant. @@ -186,15 +199,9 @@ Do not let docs drift from actual workflow. ## Out of scope in phase 0 -Do not decide yet: -- final application architecture -- final domain model -- runtime services beyond workflow tooling -- database technology -- ingestion strategy -- feature list +Phase 0 no longer blocks technical decision-making. Phase-1 baseline decisions have already been accepted. -If a task drifts into product design, stop and ask for a separate explicit decision. +Still do not treat product decisions as implicit. If a task drifts into new product scope or a major technical choice that is not yet documented, stop and ask for a separate explicit decision or ADR update. --- @@ -208,4 +215,5 @@ Avoid: - speculative optimization - introducing tools that are not yet justified -This phase is about building a clean development method first. \ No newline at end of file +This phase is about building a clean development method first. +That method now extends to implementation work that follows the accepted ADR baseline. diff --git a/README.md b/README.md index 44a6bbb..f514896 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/PHASE_1.md b/docs/PHASE_1.md index 3ff9d4d..ef9f879 100644 --- a/docs/PHASE_1.md +++ b/docs/PHASE_1.md @@ -55,3 +55,5 @@ Phase 1 is complete when: - the architecture overview exists and points to ADRs - required major technical decisions are recorded as ADRs - implementation can begin without relying on undocumented assumptions + +The current ADR baseline is sufficient to support the next implementation-oriented phase, provided future work follows the accepted decisions or explicitly supersedes them through later ADRs. diff --git a/docs/adr/README.md b/docs/adr/README.md index f5647f4..c204141 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -27,7 +27,7 @@ Each ADR should include at least: Minimal example: ```md -# ADR-0001: Example Decision +# 0001-example-decision - Status: proposed - Date: YYYY-MM-DD @@ -62,10 +62,16 @@ Use these status values: Name ADR files using a numeric prefix and a short slug: ```text -ADR-0001-short-decision-name.md -ADR-0002-another-decision.md +0001-short-decision-name.md +0002-another-decision.md ``` +The repository currently follows this convention: +- `0001-runtime-and-development-stack.md` +- `0002-initial-project-structure.md` +- `0003-containerized-developer-workflow.md` +- `0004-configuration-and-environment-strategy.md` + ## Relationship to Implementation Tasks Implementation tasks should follow documented ADRs when they depend on architecture decisions. If an implementation task exposes a new major technical decision, evaluate the options first, then record the accepted outcome in an ADR before implementation proceeds.