86 lines
2.4 KiB
Markdown
86 lines
2.4 KiB
Markdown
# 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`
|