mirror of
https://github.com/JanDeDobbeleer/oh-my-posh.git
synced 2026-08-24 02:34:19 -05:00
docs(agents): consolidate agent guidance in AGENTS.md
AGENTS.md and .github/copilot-instructions.md drifted apart, each holding sections the other lacked. Merge the Copilot file's richer content (project overview, key commands, exploration rule, src/ layout, shell integration, CLI commands, caching guardrail) into AGENTS.md and reduce the Copilot file to a pointer, so guidance lives in one place for every tool. Also corrects the segment interface name (SegmentWriter, per src/config/segment_types.go) and the artifact count (five, the list already said so). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Entire-Checkpoint: 46ce85fd9728
This commit is contained in:
Jan De Dobbeleer
committed by
Jan De Dobbeleer
Jan De Dobbeleer
co-authored by
Claude Fable 5
Claude Fable 5
parent
60232851e0
commit
4b0aa284b1
@@ -1,103 +1,5 @@
|
||||
# GitHub Copilot Instructions
|
||||
|
||||
> For full coding guidelines, commit conventions, and agent workflows, see [AGENTS.md](../AGENTS.md).
|
||||
|
||||
## Project Overview
|
||||
|
||||
Oh My Posh is a cross-shell prompt theme engine written in Go. It renders prompt segments by
|
||||
querying an `Environment` abstraction that wraps all OS/shell interactions.
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Layer | Technology |
|
||||
| --- | --- |
|
||||
| Core engine | Go - `src/` |
|
||||
| Docs site | Docusaurus (MDX) - `website/` |
|
||||
| Themes | JSON - `themes/` |
|
||||
| Config formats | TOML · JSON · YAML |
|
||||
| Installer scripts | `packages/` |
|
||||
| CI/build helpers | `build/` |
|
||||
|
||||
## Key Commands
|
||||
|
||||
```bash
|
||||
# Go — run from src/
|
||||
go test ./...
|
||||
go test ./segments/... -run TestFoo # single test
|
||||
golangci-lint run
|
||||
|
||||
# Docs — run from website/
|
||||
npm run start # local dev server
|
||||
npm run build # validate before opening a docs PR
|
||||
```
|
||||
|
||||
## Codebase Exploration
|
||||
|
||||
**Always explore the actual codebase before planning or implementing.** Do not rely on memory
|
||||
or assumptions. Use the file system tools to read relevant files first - the codebase evolves
|
||||
and the feature you're asked to add may already exist.
|
||||
|
||||
## Source Layout
|
||||
|
||||
| Path | Purpose |
|
||||
| --- | --- |
|
||||
| `src/segments/` | One `.go` + one `_test.go` per segment |
|
||||
| `src/config/segment_types.go` | Segment type registry (gob + string constants) |
|
||||
| `src/cli/` | CLI commands (Cobra); `root.go` is the entry point |
|
||||
| `src/prompt/engine.go` | Segment rendering loop |
|
||||
| `src/cache/` | Existing TTL/file/command-path cache infrastructure |
|
||||
| `src/runtime/` | `Environment` abstraction + mock |
|
||||
|
||||
## Segment Architecture
|
||||
|
||||
Every segment lives in `src/segments/` and implements the `SegmentWriter` interface. Use the
|
||||
`Environment` abstraction (`env`) for **all** OS/shell calls - never call OS APIs directly.
|
||||
|
||||
Adding a segment requires **five** artifacts (use the `segment-create` skill to scaffold):
|
||||
|
||||
1. `src/segments/<name>.go`
|
||||
2. `src/segments/<name>_test.go`
|
||||
3. `website/docs/segments/<name>.mdx`
|
||||
4. Updates to `website/sidebars.js` and `website/static/schema.json`
|
||||
5. `gob.Register(&segments.MySegment{})` in `src/config/segment_types.go`
|
||||
|
||||
Missing step 5 will cause the segment to fail silently at runtime.
|
||||
|
||||
## Shell Integration
|
||||
|
||||
`oh-my-posh init <shell>` is how users wire oh-my-posh into their shell. It:
|
||||
|
||||
1. Writes a shell-specific init script to the cache (source: `src/shell/scripts/omp.<ext>`)
|
||||
2. Returns a one-liner for the shell to `eval` - this sources the cached script, which hooks
|
||||
into prompt rendering
|
||||
|
||||
The `src/shell/` package contains per-shell logic (`pwsh.go`, `bash.go`, `zsh.go`, etc.) that
|
||||
generates the hook commands. The scripts in `src/shell/scripts/` are embedded and templated at
|
||||
init time. When modifying shell behaviour, changes typically span both the `.go` file and the
|
||||
corresponding `.ext` script.
|
||||
|
||||
Supported shells: `bash`, `zsh`, `fish`, `powershell`/`pwsh`, `cmd`, `nu`, `elvish`, `xonsh`.
|
||||
|
||||
## CLI Commands
|
||||
|
||||
CLI commands use [Cobra](https://github.com/spf13/cobra) and live in `src/cli/`. To add a new command:
|
||||
|
||||
1. Create `src/cli/<name>.go` with a `var <name>Cmd = &cobra.Command{...}`
|
||||
2. Register it in `src/cli/root.go` via `RootCmd.AddCommand(<name>Cmd)`
|
||||
|
||||
## Caching
|
||||
|
||||
`src/cache/` provides the existing caching infrastructure - use it instead of building new
|
||||
cache logic. It supports TTL-based key/value storage, file-based persistence, and command-path
|
||||
caching. Do not introduce new cache packages unless `src/cache/` genuinely cannot meet the
|
||||
requirement.
|
||||
|
||||
## Themes
|
||||
|
||||
Themes are plain JSON in `themes/`. All themes must validate against `website/static/schema.json`.
|
||||
Do not introduce breaking schema changes without updating the schema file.
|
||||
|
||||
## Documentation
|
||||
|
||||
Segment doc pages use MDX frontmatter with `title`, `sidebar_label`, and `id`. See the
|
||||
`segment-docs` skill for the canonical Go→MDX mapping.
|
||||
All agent guidance for this repository lives in [AGENTS.md](../AGENTS.md): project overview,
|
||||
key commands, architecture orientation, coding and commit conventions, skills, and the
|
||||
project-knowledge workflow. Follow it in full.
|
||||
|
||||
@@ -2,6 +2,11 @@
|
||||
|
||||
General coding guidelines, commit conventions, and agent workflows for this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
Oh My Posh is a cross-shell prompt theme engine written in Go. It renders prompt segments by
|
||||
querying an `Environment` abstraction that wraps all OS/shell interactions.
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Layer | Technology |
|
||||
@@ -13,6 +18,25 @@ General coding guidelines, commit conventions, and agent workflows for this repo
|
||||
| Package/installer scripts | `packages/` |
|
||||
| Build scripts | `build/` |
|
||||
|
||||
## Key Commands
|
||||
|
||||
```bash
|
||||
# Go - run from src/
|
||||
go test ./...
|
||||
go test ./segments/... -run TestFoo # single test
|
||||
golangci-lint run
|
||||
|
||||
# Docs - run from website/
|
||||
npm run start # local dev server
|
||||
npm run build # validate before opening a docs PR
|
||||
```
|
||||
|
||||
## Codebase Exploration
|
||||
|
||||
**Always explore the actual codebase before planning or writing code.** Do not rely on memory
|
||||
or assumptions. Use the file system tools to read relevant files first - the codebase evolves
|
||||
and the feature you're asked to add may already exist.
|
||||
|
||||
## Repository Layout
|
||||
|
||||
```text
|
||||
@@ -26,35 +50,74 @@ packages/ # Installer/package manifests
|
||||
build/ # CI build helpers
|
||||
```
|
||||
|
||||
Key paths inside `src/`:
|
||||
|
||||
| Path | Purpose |
|
||||
| ----------------------------- | --------------------------------------------------- |
|
||||
| `src/segments/` | One `.go` + one `_test.go` per segment |
|
||||
| `src/config/segment_types.go` | Segment type registry (gob + string constants) |
|
||||
| `src/cli/` | CLI commands (Cobra); `root.go` is the entry point |
|
||||
| `src/prompt/engine.go` | Segment rendering loop |
|
||||
| `src/cache/` | Existing TTL/file/command-path cache infrastructure |
|
||||
| `src/runtime/` | `Environment` abstraction + mock |
|
||||
|
||||
## Segment Development
|
||||
|
||||
When adding a new segment, four artifacts are required - use the `segment-create` skill
|
||||
to scaffold all of them automatically:
|
||||
Every segment lives in `src/segments/` and implements the `SegmentWriter` interface. Use the
|
||||
`Environment` abstraction (`env`) for **all** OS/shell calls - never call OS APIs directly.
|
||||
|
||||
1. `src/segments/<name>.go` - segment implementation
|
||||
Adding a segment requires **five** artifacts - use the `segment-create` skill to scaffold all
|
||||
of them automatically:
|
||||
|
||||
1. `src/segments/<name>.go` - segment source
|
||||
2. `src/segments/<name>_test.go` - unit tests
|
||||
3. `website/docs/segments/<name>.mdx` - user-facing docs
|
||||
4. Update `website/sidebars.js` and `website/static/schema.json`
|
||||
5. Register the type in `src/config/segment_types.go` via `gob.Register(&segments.MySegment{})` - missing this causes
|
||||
silent failures at runtime
|
||||
5. Register the type in `src/config/segment_types.go` via `gob.Register(&segments.MySegment{})`
|
||||
|
||||
Missing step 5 causes the segment to fail silently at runtime.
|
||||
|
||||
See the `segment-docs` skill for the canonical mapping between Go source constructs and MDX
|
||||
documentation fields (template properties, type representations, option tables).
|
||||
|
||||
## Shell Integration
|
||||
|
||||
`oh-my-posh init <shell>` is how users wire oh-my-posh into their shell. It:
|
||||
|
||||
1. Writes a shell-specific init script to the cache (source: `src/shell/scripts/omp.<ext>`)
|
||||
2. Returns a one-liner for the shell to `eval` - this sources the cached script, which hooks
|
||||
into prompt rendering
|
||||
|
||||
The `src/shell/` package contains per-shell logic (`pwsh.go`, `bash.go`, `zsh.go`, etc.) that
|
||||
generates the hook commands. The scripts in `src/shell/scripts/` are embedded and templated at
|
||||
init time. When modifying shell behaviour, changes typically span both the `.go` file and the
|
||||
corresponding script.
|
||||
|
||||
Supported shells: `bash`, `zsh`, `fish`, `powershell`/`pwsh`, `cmd`, `nu`, `elvish`, `xonsh`.
|
||||
|
||||
## CLI Commands
|
||||
|
||||
CLI commands use [Cobra](https://github.com/spf13/cobra) and live in `src/cli/`. To add a new
|
||||
command:
|
||||
|
||||
1. Create `src/cli/<name>.go` with a `var <name>Cmd = &cobra.Command{...}`
|
||||
2. Register it in `src/cli/root.go` via `RootCmd.AddCommand(<name>Cmd)`
|
||||
|
||||
## Caching
|
||||
|
||||
`src/cache/` provides the existing caching infrastructure - use it instead of building new
|
||||
cache logic. It supports TTL-based key/value storage, file-based persistence, and command-path
|
||||
caching. Do not introduce new cache packages unless `src/cache/` genuinely cannot meet the
|
||||
requirement.
|
||||
|
||||
## Go Conventions
|
||||
|
||||
- Follow the `golang` skill for project-specific Go standards.
|
||||
- Each segment implements the `Segment` interface; use `env` (the `Environment` abstraction)
|
||||
for all OS/shell calls - never call OS APIs directly.
|
||||
- Test with `go test ./...` from `src/`.
|
||||
- Lint with `golangci-lint run` from `src/`.
|
||||
Follow the `golang` skill for project-specific Go standards.
|
||||
|
||||
## Documentation (website/)
|
||||
|
||||
- Follow the `markdown` skill for `.md`/`.mdx` formatting rules.
|
||||
- Segment doc pages live in `website/docs/segments/` and use MDX frontmatter with `title`, `sidebar_label`, and `id`.
|
||||
- Run `npm run start` inside `website/` for a local dev server.
|
||||
- Run `npm run build` inside `website/` to verify the site builds before opening a docs PR.
|
||||
|
||||
## PowerShell
|
||||
|
||||
|
||||
Reference in New Issue
Block a user