120 lines
4.1 KiB
Markdown
120 lines
4.1 KiB
Markdown
# AGENTS Guide
|
|
|
|
This file documents repository-specific operational guidance for coding agents.
|
|
|
|
## Scope
|
|
|
|
- Repository: `zphinx/tai`
|
|
- Git host: `https://git.archflux.net`
|
|
- Preferred release CLI: `tea`
|
|
|
|
## Tea CLI: Required Practices
|
|
|
|
### 0. Agent policy: use tea for Gitea operations
|
|
|
|
- Agents should use `tea` as the default interface for Gitea interactions in this repository.
|
|
- Prefer `tea` for release management and remote state checks instead of ad-hoc API calls.
|
|
- Keep using `git` for source control operations (commit/merge/tag/push), and use `tea` for release objects and Gitea-facing workflows.
|
|
|
|
### 1. Verify command syntax for installed tea version
|
|
|
|
The installed version may not match upstream examples. Always check help first:
|
|
|
|
```fish
|
|
tea --version
|
|
tea logins --help
|
|
tea releases --help
|
|
```
|
|
|
|
Important version-specific note observed in this repo:
|
|
|
|
- `tea logins add` is valid (not `tea login add`)
|
|
- `--default` is not supported on `add` in this version
|
|
- Set default with `tea logins default <name>`
|
|
|
|
### 2. Login setup flow
|
|
|
|
Use environment token (do not hardcode tokens in commands/files):
|
|
|
|
```fish
|
|
set -x GITEA_TOKEN "<token>"
|
|
tea logins add --name archflux --url https://git.archflux.net --token "$GITEA_TOKEN"
|
|
tea logins default archflux
|
|
tea logins ls
|
|
```
|
|
|
|
### 3. Token safety
|
|
|
|
- Never print raw tokens in logs, commit messages, or docs.
|
|
- If a token is exposed, revoke it immediately in Gitea and create a replacement.
|
|
|
|
### 4. Release workflow expectations in this repo
|
|
|
|
Tag workflow file: `.gitea/workflows/tag.yml`
|
|
|
|
Observed behavior:
|
|
|
|
- Workflow trigger pattern is numeric tags: `[0-9]*`
|
|
- Tag `0.x.y` triggers build workflow
|
|
- Tag `v0.x.y` can still be published as alias, but does not match that workflow trigger
|
|
|
|
Recommended tagging pattern for releases:
|
|
|
|
```fish
|
|
git tag -a 0.6.0 -m "0.6.0"
|
|
git tag -a v0.6.0 -m "v0.6.0"
|
|
git push origin 0.6.0
|
|
git push origin v0.6.0
|
|
```
|
|
|
|
### 5. Create release object with tea
|
|
|
|
```fish
|
|
tea releases create --repo zphinx/tai --tag 0.6.0 --title "v0.6.0" --note "<release notes>"
|
|
tea releases list --repo zphinx/tai
|
|
```
|
|
|
|
### 6. Agent release checklist
|
|
|
|
Before release:
|
|
|
|
1. Confirm branch state is clean.
|
|
2. Run tests/lint (`pytest`, `ruff`).
|
|
3. Merge to `main`.
|
|
4. Create/push tags (`0.x.y` + optional `v0.x.y`).
|
|
5. Create release entry with `tea`.
|
|
6. Verify in `tea releases list`.
|
|
|
|
## Non-Goals for Agents
|
|
|
|
- Do not force Kubernetes deployment guidance for current architecture.
|
|
- Treat Docker as one-shot execution model with mounted persistent volumes for runbooks/sessions/logs.
|
|
|
|
## CI Pipeline: Man-Page Validation
|
|
|
|
The man-page drift detection is **automatically integrated** into `.gitea/workflows/ci.yml`:
|
|
|
|
- **Test name:** `test_man_page_covers_cli_long_options()` in `tests/test_cli.py`
|
|
- **Trigger:** Runs on every push and pull request (as part of the `Test` step)
|
|
- **Behavior:** Extracts all long options from `tai --help` and verifies each is documented in `docs/tai.1`
|
|
- **Failure mode:** CI fails if any long option in CLI is missing from man page; prevents merge of undocumented options
|
|
|
|
### How to Fix Failed Man-Page Validation
|
|
|
|
1. **Identify missing options:** CI output shows "Missing options in docs/tai.1: ..."
|
|
2. **Update docs/tai.1:** Add the missing option to the appropriate section (command or global options)
|
|
3. **Re-run tests locally:** `python -m pytest tests/test_cli.py::test_man_page_covers_cli_long_options -v`
|
|
4. **Push to trigger CI:** Once local test passes, push the update to trigger CI validation
|
|
|
|
### Man-Page Maintenance Workflow
|
|
|
|
- **When adding CLI options:** Add to `src/tai/cli.py` and immediately update `docs/tai.1` in the same commit
|
|
- **When removing CLI options:** Remove from `src/tai/cli.py` and update `docs/tai.1` in the same commit
|
|
- **When renaming CLI options:** Update both CLI code and `docs/tai.1` in one commit
|
|
- **When changing option behavior/defaults:** Update the option description in `docs/tai.1` to reflect new behavior
|
|
|
|
## Documentation Maintenance
|
|
|
|
- When adding or changing CLI commands/options, update `docs/tai.1` in the same change.
|
|
- Keep `README.md` and `docs/tai.1` aligned for user-facing flags and examples.
|