From 51387c807574d813a2902f759189447c9133cbea Mon Sep 17 00:00:00 2001 From: jwfing Date: Tue, 14 Jul 2026 18:17:45 -0700 Subject: [PATCH 1/2] docs: add CLAUDE.md; enrich developing-insta-cli with src/ architecture Add a repo-local CLAUDE.md (always-on rules + pointer to the skill) and fold a src/ architecture map + the cli-reference.md sync rule into the existing developing-insta-cli skill. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/skills/developing-insta-cli/SKILL.md | 17 +++++++++++++++ CLAUDE.md | 23 ++++++++++++++++++++ 2 files changed, 40 insertions(+) create mode 100644 CLAUDE.md diff --git a/.claude/skills/developing-insta-cli/SKILL.md b/.claude/skills/developing-insta-cli/SKILL.md index df14b85..89bf590 100644 --- a/.claude/skills/developing-insta-cli/SKILL.md +++ b/.claude/skills/developing-insta-cli/SKILL.md @@ -19,6 +19,23 @@ npx tsx src/index.ts --help # run the CLI from source - `project create|link` has side effects in cwd (`.insta/`, observe hook, agent skills) — exercise them only in scratch dirs. - End-to-end without the cloud: run the insta-oss daemon and point the CLI at it with `INSTA_API_URL` (env wins over persisted config since v0.0.7). +## Architecture (`src/`) + +| Path | Responsibility | +|------|----------------| +| `index.ts` | commander program — registers every command | +| `api.ts` | typed platform-API client (auth headers, token refresh, error mapping) | +| `config.ts` | global `~/.insta/config.json` (apiUrl + tokens + user) · project `./.insta/project.json` (projectId / orgId / current branch) | +| `commands/` | one file per command group: `auth` `org` `project` `services` `branch` `secrets` `deploy` `compute` `upgrade` `metrics` (+`logs`) `billing` `govern` (policy/approvals) `manifest` `observe` | +| `observe/` | local `insta observe` hook — `scanner.ts` (AWS/GitHub/Stripe/LLM/DB cred detection), `hook.ts`, `install.ts`, `report.ts` (→ platform event ingest) | +| `flyctl-build.ts` | source-directory deploy build glue (Fly build context) | +| `ensure-skills.ts` | installs/refreshes the agent skills into the user's project | +| `util.ts` | shared helpers | + +- **Command/flag changes must be mirrored in `skills/insta/cli-reference.md`** (the superproject + `skills/` submodule) — that reference doc is how agents learn the CLI surface, so a new or + renamed command/flag is only half-done until it's updated there, in the same change set. + ## Getting a PR merged (main is protected — this exact flow, no other works) 1. Branch from `origin/main`: `feat/*` or `fix/*`. PRs target `main`. **Squash merge.** diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..adb1dee --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,23 @@ +# insta-cli — agent notes + +The `insta` CLI — a **thin client** of the [platform](../platform) control-plane API for +project / branch / secrets / deploy / governance, built for developers and agents. Node 20 + TS +(ESM) + commander; every command wraps a platform API call. A submodule of the **insta-cloud** +superproject. + +## Non-negotiables + +1. `main` is branch-protected — **PR only** (squash), needs 1 approving review you can't self-cast. + Develop on a `feat/*` or `fix/*` branch off `main`. +2. When working inside the insta-cloud superproject: commit + push **here first**, then bump the + `cli` pointer in the superrepo — never the reverse. (Git mechanics: superproject + `developing-on-insta-cloud` skill.) +3. Pre-commit gate: `npm run typecheck && npm test`. +4. Command/flag changes must be mirrored in `skills/insta/cli-reference.md` (superproject `skills/` + submodule) — that's the agent-facing surface doc. + +## Developing here + +See the **developing-insta-cli** skill (`.claude/skills/developing-insta-cli/`) for the dev loop, +`src/` architecture, the PR-merge/approval flow, the release process (binaries + npm OIDC), and +gotchas. From 9b6d7fe49ad48e8e36bca437efde0d2b961cc518 Mon Sep 17 00:00:00 2001 From: jwfing Date: Tue, 14 Jul 2026 19:01:21 -0700 Subject: [PATCH 2/2] docs: move always-on notes to AGENTS.md; CLAUDE.md -> @AGENTS.md Split repo-local agent notes into AGENTS.md (read by Claude Code, Codex, and other AGENTS.md-aware tools); CLAUDE.md imports it via @AGENTS.md, matching the frontend/ convention. The developing-* skill stays in .claude/skills/ (Claude Code's skill dir); AGENTS.md points to the SKILL.md file so other agents can read it directly. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 23 +++++++++++++++++++++++ CLAUDE.md | 24 +----------------------- 2 files changed, 24 insertions(+), 23 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..6848c15 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,23 @@ +# insta-cli — agent notes + +The `insta` CLI — a **thin client** of the [platform](../platform) control-plane API for +project / branch / secrets / deploy / governance, built for developers and agents. Node 20 + TS +(ESM) + commander; every command wraps a platform API call. A submodule of the **insta-cloud** +superproject. + +## Non-negotiables + +1. `main` is branch-protected — **PR only** (squash), needs 1 approving review you can't self-cast. + Develop on a `feat/*` or `fix/*` branch off `main`. +2. When working inside the insta-cloud superproject: commit + push **here first**, then bump the + `cli` pointer in the superrepo — never the reverse. (Git mechanics: superproject + `developing-on-insta-cloud` skill.) +3. Pre-commit gate: `npm run typecheck && npm test`. +4. Command/flag changes must be mirrored in `skills/insta/cli-reference.md` (superproject `skills/` + submodule) — that's the agent-facing surface doc. + +## Developing here + +The full dev guide — dev loop, `src/` architecture, the PR-merge/approval flow, the release +process (binaries + npm OIDC), and gotchas — is in `.claude/skills/developing-insta-cli/SKILL.md`. +Claude Code loads it as a skill on demand; other agents (Codex, etc.) can read that file directly. diff --git a/CLAUDE.md b/CLAUDE.md index adb1dee..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,23 +1 @@ -# insta-cli — agent notes - -The `insta` CLI — a **thin client** of the [platform](../platform) control-plane API for -project / branch / secrets / deploy / governance, built for developers and agents. Node 20 + TS -(ESM) + commander; every command wraps a platform API call. A submodule of the **insta-cloud** -superproject. - -## Non-negotiables - -1. `main` is branch-protected — **PR only** (squash), needs 1 approving review you can't self-cast. - Develop on a `feat/*` or `fix/*` branch off `main`. -2. When working inside the insta-cloud superproject: commit + push **here first**, then bump the - `cli` pointer in the superrepo — never the reverse. (Git mechanics: superproject - `developing-on-insta-cloud` skill.) -3. Pre-commit gate: `npm run typecheck && npm test`. -4. Command/flag changes must be mirrored in `skills/insta/cli-reference.md` (superproject `skills/` - submodule) — that's the agent-facing surface doc. - -## Developing here - -See the **developing-insta-cli** skill (`.claude/skills/developing-insta-cli/`) for the dev loop, -`src/` architecture, the PR-merge/approval flow, the release process (binaries + npm OIDC), and -gotchas. +@AGENTS.md