[codex] refresh README and AGENTS docs #262
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,44 +1,70 @@ | ||
| # Repository Guidelines | ||
|
|
||
| ## Project Identity | ||
| This repo is the ShellTime CLI and daemon. Public-facing docs, command examples, and product references should use `ShellTime` and `shelltime.xyz`. | ||
|
|
||
| Code and imports currently use the module path `github.com/malamtime/cli`. Do not "fix" ShellTime branding in docs just because the module path says `malamtime`; the mismatch is intentional in the current repo state. | ||
|
|
||
| ## Project Structure & Package Boundaries | ||
| This is a Go monorepo for the ShellTime CLI and daemon. | ||
|
|
||
| - `cmd/cli/main.go`: CLI entrypoint for `shelltime` | ||
| - `cmd/daemon/main.go`: daemon entrypoint for `shelltime-daemon` | ||
| - `commands/`: CLI command definitions and user-facing command behavior | ||
| - `daemon/`: background services, socket handling, processors, and OTEL handlers | ||
| - `model/`: config, API clients, shell integrations, crypto, and shared domain logic | ||
| - `docs/`: user-facing docs such as `CONFIG.md` and `CC_STATUSLINE.md` | ||
| - `fixtures/`: reusable test fixtures | ||
|
|
||
| Keep new code inside the existing package boundary. Do not mix CLI wiring, daemon internals, and model logic in the same package. | ||
|
|
||
| ## Build, Test, and Development Commands | ||
|
|
||
| - `go build -o shelltime ./cmd/cli/main.go`: build the CLI binary | ||
| - `go build -o shelltime-daemon ./cmd/daemon/main.go`: build the daemon binary | ||
| - `go test -timeout 3m -coverprofile=coverage.txt -covermode=atomic ./...`: run the full suite with coverage | ||
| - `go test ./commands/...`: run command-package tests | ||
| - `go test ./daemon/...`: run daemon-package tests | ||
| - `go test ./model/...`: run model-package tests | ||
| - `go test -run TestName ./daemon/`: run a targeted daemon test | ||
| - `go fmt ./...`: format Go code | ||
| - `go vet ./...`: run static analysis | ||
| - `mockery`: regenerate mocks when interfaces change | ||
| - `pp g`: regenerate PromptPal-generated artifacts when relevant | ||
|
|
||
| Use Go 1.26, as declared in `go.mod`. | ||
|
|
||
| ## Coding Style & Naming Conventions | ||
| Use standard Go conventions and keep code `gofmt`-clean. | ||
|
|
||
| - File naming: lowercase with underscores or dotted qualifiers such as `daemon.install.go` or `api.base.go` | ||
| - Tests: `*_test.go` with clear `TestXxx` names | ||
| - Prefer table-driven tests for pure logic | ||
| - Use `testify` suites for stateful daemon flows | ||
| - Keep comments brief and only where they reduce real ambiguity | ||
|
|
||
| ## Testing Guidance | ||
|
|
||
| - Put reusable payloads and fixtures under `fixtures/` | ||
| - Prefer package-level test runs while iterating, then run the full suite before finishing | ||
| - Ensure `go test -timeout 3m -coverprofile=coverage.txt -covermode=atomic ./...` passes before opening a PR or cutting a release | ||
|
|
||
| ## Documentation Maintenance | ||
| When command behavior, setup flow, config formats, or integrations change, update the docs in the same change. | ||
|
|
||
| - `README.md`: concise user-facing overview, install/setup flow, current command surface, and links | ||
| - `docs/CONFIG.md`: detailed config semantics, file locations, defaults, and OTEL settings | ||
| - `docs/CC_STATUSLINE.md`: Claude Code statusline behavior, formatting, and platform notes | ||
| - `AGENTS.md`: contributor and agent workflow guidance for this repo | ||
|
|
||
| Do not leave `README.md` advertising commands that no longer exist, and do not document new commands only in code. | ||
|
|
||
| ## Commit & Pull Request Guidelines | ||
| History follows Conventional Commits with scope, for example: | ||
|
|
||
| - `fix(daemon): ...` | ||
| - `feat(commands): ...` | ||
| - `refactor(model): ...` | ||
| - `docs(readme): ...` | ||
|
|
||
| Keep commits focused on one behavioral change. PRs should include a short summary, why the change is needed, and test evidence. Link related issues when applicable. If behavior or output changes, include CLI examples or screenshots. Regenerate artifacts such as `pp g` and `mockery` when needed so CI remains green. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Go 1.26 is not a released version (the current stable version is 1.23). This is likely a typo for the version actually declared in
go.mod(e.g., 1.22 or 1.23).