bisco/hoopscout-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
81834f3254e631b8dce937c6ff35257e024cbfac
hoopscout-v2/README.md

4.4 KiB
Raw Blame History

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.

.
|-- .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.