Merge branch 'feature/phase-1-doc-alignment' into develop
This commit is contained in:
bisco
34
AGENTS.md
34
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.
|
||||
|
||||
---
|
||||
|
||||
@ -209,3 +216,4 @@ Avoid:
|
||||
- introducing tools that are not yet justified
|
||||
|
||||
This phase is about building a clean development method first.
|
||||
That method now extends to implementation work that follows the accepted ADR baseline.
|
||||
|
||||
51
README.md
51
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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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.
|
||||
|
||||
Reference in New Issue
Block a user