bisco/hoopscout-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f19da9877890076fcf7b5f63864bbcdb1250de74
hoopscout-v2/docs/MACHINE_SETUP.md
bisco 44aa06a3a8 docs: close out phase 0 workflow foundation
2026-03-20 19:23:30 +01:00

2.4 KiB
Raw Blame History

Machine Setup

Purpose

This document describes the minimum setup needed to continue repository work from a different machine. It is intended as a quick-start handoff for working with HoopScout v2 phase 0 using Codex and repository-defined agent workflows.

What Is Local-Only

These remain local responsibilities and should not be treated as repository-owned configuration:

  • Codex authentication
  • personal shell aliases
  • personal editor preferences
  • secrets
  • API keys
  • machine-specific paths unless only documented as examples

What Is Repository-Owned

These should be read from the repository and kept aligned in version control:

  • workflow rules
  • branch policy
  • task format
  • agent roles
  • setup instructions
  • test execution instructions
  • docs for humans and agents

Minimal Bootstrap Flow

Use this sequence on a new machine:

  1. Clone the repository.
  2. Checkout develop.
  3. Authenticate Codex locally.
  4. Read:
    • AGENTS.md
    • docs/WORKFLOW.md
    • docs/MACHINE_SETUP.md
    • docs/TASK_TEMPLATE.md
  5. Run make doctor.
  6. Create a task branch from develop.

Validation Checklist

A machine is ready for repository work when:

  • repository is cloned
  • correct branch is checked out
  • Codex auth is working
  • AGENTS.md is present
  • .codex/config.toml is present
  • .codex/agents/ is present
  • .agents/skills/ is present
  • docs/WORKFLOW.md is present
  • docs/MACHINE_SETUP.md is present
  • docs/TASK_TEMPLATE.md is present
  • make doctor works

Local Checks

Run make doctor during bootstrap to verify the repository bootstrap and local working assumptions.

Troubleshooting

Wrong Branch Checked Out

Return to develop, update local state if needed, and create the correct task branch from there.

Codex Not Authenticated

Complete Codex authentication locally on the machine before continuing. Authentication is not stored in the repository.

Missing Repository Files

Confirm the repository was cloned correctly and that required tracked files such as AGENTS.md, .codex/config.toml, and the docs/ files are present.

Local Assumptions Do Not Match Repository Instructions

Follow the repository instructions rather than local habits. If the repository guidance is incomplete or outdated, update the tracked docs instead of relying on undocumented local behavior.

Related Files

  • AGENTS.md
  • docs/WORKFLOW.md
  • docs/TASK_TEMPLATE.md
  • .codex/config.toml