doitintl · apgiorgi · Jun 25, 2026 · Jul 7, 2026
@@ -0,0 +1,86 @@
+# Agent Guide
+
+Guidance for AI agents working with this repository. The etiquette section applies to external agents — agents not acting on the maintainer's direct instructions. The project context applies to everyone.
+
+## Etiquette for External Agents
+
+This section is for agents acting on their own initiative, or on behalf of someone other than the maintainer. Agents working on the maintainer's direct instructions follow those instructions instead.
+
+This repo is one piece of a much larger system. `dci` wraps restish, sits in front of the DCI API, and ships through multiple distribution channels. A change that looks correct from the code alone may conflict with things in flight — the API roadmap, planned CLI changes, or packaging constraints — that live nowhere in this repo.
+
+**Read the history before proposing anything.** Closed issues carry decisions, not just resolved bugs. Rejected approaches, deliberate constraints, and "why we didn't do X" reasoning are all documented there. Reading only open issues gives an incomplete picture.
+
+**Maintainer first.** The maintainer has context that isn't in this repo: the DCI API roadmap, internal usage patterns, and work already in progress. Before taking any action that affects the repo's public surface, check with the maintainer first.
+
+### Preferred contribution flow
+
+**Open an issue. Do not open a PR.**
+
+PRs are cheap to create and expensive to decline. An unsolicited PR puts the maintainer in the position of managing work they didn't ask for. An issue lets an idea be evaluated, shaped, or discarded before any implementation happens.
+
+The maintainer prefers to open PRs themselves — when and if a change is wanted, using their own agent, with full context. If you identify something worth addressing:
+
+1. Search open **and closed** issues first. The idea may have already been evaluated and decided.
+2. Open an issue describing the **problem**, not the solution. Explain what's broken or missing and why it matters. Include your observations, not just your conclusions.
+3. Stop there. Do not implement. Do not open a PR. Wait for maintainer input.
+
+If a maintainer explicitly asks you to open a PR, proceed. Otherwise, don't.
+
+The same policy applies to human contributors — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+### What a good issue looks like
+
+- **Problem first.** What is broken or missing, and what's the impact?
+- **Observations, not just conclusions.** What did you find? What did you read?
+- **Scope flags.** Does this touch the release pipeline, distribution manifests, the DCI API contract, or restish internals? Call it out — these areas are most likely to have invisible constraints.
+- **No solution required.** You may propose one, but it's not the deliverable. The maintainer may have a better approach or may decide not to act at all.
+
+## Project Context
+
+### What Is This
+
+`dci` is the CLI for the DoiT Cloud Intelligence (DCI) API. It wraps [restish](https://github.com/rest-sh/restish) with DCI-specific configuration — auto-configured API base, OAuth2 via the DoiT Console, table-first output, and a locked-down command surface that exposes only DCI API operations. The entire CLI is a single `main.go` file. It ships as a Go binary distributed via Homebrew, Scoop, WinGet, and `.deb`/`.rpm` packages.
+
+### Restish Version (don't upgrade to v2)
+
+Pinned to restish **v0.21.2** (already includes the CVE-2025-22868 patch). Restish **v2** is a ground-up redesign that **deletes the in-process library model `dci` is built on** — it makes restish the binary and pushes extensions to out-of-process plugins, so moving to v2 is a rewrite, not a dependency bump, with no security pressure and real UX regressions. **Don't upgrade without revisiting the full evaluation in [issue #20](https://github.com/doitintl/dci-cli/issues/20).**
+
+### Commit Message Conventions
+
+GoReleaser changelog auto-generates from commits between tags. Filtered prefixes (excluded from changelog):
+- `docs:` — documentation-only changes (README, DISTRIBUTION.md, etc.)
+- `test:` — test-only changes
+- `chore:` — maintenance (manifest updates, CI config, dependency bumps, PR review fixups, secrets/CI fixes)
+
+GoReleaser also filters merge commits (`Merge ...`) and auto-generated manifest commits (`Update Homebrew formula ...`) automatically.
+
+**Use `chore:` for anything not user-facing** — CI/CD fixes, gitleaks config, PR review nits, and internal tooling. Use `fix:` only for bugs that affect CLI users. Commits without a filtered prefix appear in the GitHub Release changelog.
+
+### Release Pipeline
+
+- GoReleaser v2 via `goreleaser-cross` Docker image
+- Tag `v*` triggers `release.yml` → `sync-manifests.yml` + `post-release-verify.yml`
+- Manifests (`Formula/dci.rb`, `bucket/dci.json`) are committed to main by CI
+- WinGet manifests submitted automatically via PR to `microsoft/winget-pkgs`
+
+### Key Files
+
+- Single-file CLI: `main.go` (all logic) + `main_test.go`
+- Build config: `.goreleaser.yaml`
+- Release workflows: `.github/workflows/release.yml`, `sync-manifests.yml`, `post-release-verify.yml`
+- Package templates: `packaging/`
+
+#### Why `main.go` is a single file
+
+This is intentional. The CLI has no external package consumers, so splitting into sub-packages would buy nothing but churn. A single file is easy to grep, easy to read linearly, and matches how restish-wrapper CLIs are typically structured.
+
+The file is organized into chapters (in order): config & onboarding → arg/completion normalization → usage branding & lockdown → auth & doer context → customer context → skills embed → output flags & table rendering.
+
+**When to split:** if `main.go` grows past ~2,500 lines or any single chapter exceeds ~700 lines, break along chapter boundaries into sibling files in the same `package main` (e.g. `table.go`, `auth.go`, `config.go`). Do not introduce sub-packages — there is no external API surface to justify them.
+
+### Project Conventions
+
+- README and DISTRIBUTION.md are user-facing — no internal jargon, no restish references
+- README targets end users; DISTRIBUTION.md targets developers/contributors
+- Homebrew tap works via GitHub redirect (`doitintl/homebrew-dci-cli` → `doitintl/dci-cli`)
+- Windows ARM64 excluded (upstream goreleaser-cross issue #117)
@@ -1,41 +1 @@
-# Claude Code Project Context
-
-## What Is This
-
-`dci` is the CLI for the DoiT Cloud Intelligence (DCI) API. It wraps [restish](https://github.com/rest-sh/restish) with DCI-specific configuration — auto-configured API base, OAuth2 via the DoiT Console, table-first output, and a locked-down command surface that exposes only DCI API operations. The entire CLI is a single `main.go` file. It ships as a Go binary distributed via Homebrew, Scoop, WinGet, and `.deb`/`.rpm` packages.
-
-## Restish Version (don't upgrade to v2)
-
-Pinned to restish **v0.21.2** (already includes the CVE-2025-22868 patch). Restish **v2** is a ground-up redesign that **deletes the in-process library model `dci` is built on** — it makes restish the binary and pushes extensions to out-of-process plugins, so moving to v2 is a rewrite, not a dependency bump, with no security pressure and real UX regressions. **Don't upgrade without revisiting the full evaluation in [issue #20](https://github.com/doitintl/dci-cli/issues/20).**
-
-## Commit Message Conventions
-
-GoReleaser changelog auto-generates from commits between tags. Filtered prefixes (excluded from changelog):
-- `docs:` — documentation-only changes (README, DISTRIBUTION.md, etc.)
-- `test:` — test-only changes
-- `chore:` — maintenance (manifest updates, CI config, dependency bumps, PR review fixups, secrets/CI fixes)
-
-Goreleaser also filters merge commits (`Merge ...`) and auto-generated manifest commits (`Update Homebrew formula ...`) automatically.
-
-**Use `chore:` for anything not user-facing** — CI/CD fixes, gitleaks config, PR review nits, and internal tooling. Use `fix:` only for bugs that affect CLI users. Commits without a filtered prefix appear in the GitHub Release changelog.
-
-## Release Pipeline
-
-- GoReleaser v2 via `goreleaser-cross` Docker image
-- Tag `v*` triggers `release.yml` → `sync-manifests.yml` + `post-release-verify.yml`
-- Manifests (`Formula/dci.rb`, `bucket/dci.json`) are committed to main by CI
-- WinGet manifests submitted automatically via PR to `microsoft/winget-pkgs`
-
-## Key Files
-
-- Single-file CLI: `main.go` (all logic) + `main_test.go`
-- Build config: `.goreleaser.yaml`
-- Release workflows: `.github/workflows/release.yml`, `sync-manifests.yml`, `post-release-verify.yml`
-- Package templates: `packaging/`
-
-## Project Conventions
-
-- README and DISTRIBUTION.md are user-facing — no internal jargon, no restish references
-- README targets end users; DISTRIBUTION.md targets developers/contributors
-- Homebrew tap works via GitHub redirect (`doitintl/homebrew-dci-cli` → `doitintl/dci-cli`)
-- Windows ARM64 excluded (upstream goreleaser-cross issue #117)
+@AGENTS.md
@@ -0,0 +1,17 @@
+# Contributing
+
+Thanks for your interest in `dci`.
+
+**Please open an issue instead of a pull request.** This CLI is one piece of a larger system, and a change that looks correct in isolation may conflict with work in flight — the API roadmap, planned CLI changes, or packaging constraints that aren't visible in this repo. The maintainer prefers to evaluate ideas as issues and open PRs themselves when a change is wanted.
+
+Before opening an issue, search open **and closed** issues — closed issues document decisions and rejected approaches, not just fixed bugs.
+
+A good issue:
+
+- Describes the **problem**, not just a solution — what's broken or missing, and why it matters.
+- Includes your observations, not only your conclusions.
+- Flags scope: anything touching the release pipeline, distribution manifests, or API behavior is most likely to have invisible constraints.
+
+If a maintainer explicitly asks you to open a PR, go ahead. Otherwise, please don't.
+
+AI agents: see [AGENTS.md](AGENTS.md) for the full guidance.