bisco/hoopscout-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f3f7d922db5b629fa60ed5e4e6f7712a06d71bea
hoopscout-v2/docs/MACHINE_SETUP.md
bisco f3f7d922db docs: define machine setup guidance
2026-03-20 19:16:39 +01:00

2.2 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. 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
  • docs are present
  • make doctor works

Local Checks

Run make doctor 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