From 5e5ec063bf3c2079b461204e933d5de1587ec9fe Mon Sep 17 00:00:00 2001 From: "molecule-ai[bot]" <276602405+molecule-ai[bot]@users.noreply.github.com> Date: Mon, 20 Apr 2026 23:10:40 +0000 Subject: [PATCH] docs: add CLAUDE.md, known-issues.md, and .claude/settings.json (#2) * docs: add CLAUDE.md for agent onboarding Inherits platform conventions from molecule-core: - Cron discipline and triage rules - Build/test commands (go build, go test) - Go module conventions (go mod tidy, go.sum hygiene) - Release process (GoReleaser tag workflow) - CLI design conventions (kubectl/gh patterns, stderr errors, exit codes) - Stub repo status checklist Co-Authored-By: Claude Sonnet 4.6 * docs: add CLAUDE.md known-issues ref, known-issues.md, .claude/settings.json - CLAUDE.md: add known-issues.md reference in Known Issues section - known-issues.md: 5 entries (KI-001 main.go, KI-002 API client, KI-003 go.sum, KI-004 goreleaser, KI-005 no tests) - .claude/settings.json: permissions for go/goreleaser tools, PreToolUse Bash hook, cleanupPeriodDays 30 Co-Authored-By: Claude Sonnet 4.6 --------- Co-authored-by: Molecule AI SDK-Dev Co-authored-by: Claude Sonnet 4.6 --- .claude/settings.json | 34 ++++++++++ CLAUDE.md | 152 ++++++++++++++++++++++++++++++++++++++++++ known-issues.md | 149 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 335 insertions(+) create mode 100644 .claude/settings.json create mode 100644 CLAUDE.md create mode 100644 known-issues.md diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..23de822 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,34 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "permissions": { + "allow": [ + "Bash(git *)", + "Bash(go *)", + "Bash(goreleaser *)", + "Bash(gofmt *)", + "Bash(golint *)", + "Bash(govulncheck *)", + "Read", + "Glob", + "Grep" + ], + "deny": [ + "Bash(git push --force *)" + ] + }, + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "echo 'Bash executed'", + "once": true + } + ] + } + ] + }, + "cleanupPeriodDays": 30 +} diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..ff27b32 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,152 @@ +# molecule-cli + +Go CLI for the Molecule AI agent platform. Wraps the platform's workspace runtime and control plane APIs, providing a unified command-line interface for managing agents, workspaces, and deployments. + +**Users:** Platform operators and developers integrating with the Molecule AI platform. + +**Repo state (2026-04-16):** Thin/stub. Go module is initialized; core CLI commands are not yet implemented. CI (Go binary release via GoReleaser + GitHub Actions) is wired up. + +--- + +## 1. Project Overview + +This CLI is the primary user-facing tool for interacting with the Molecule AI platform. Typical responsibilities: + +- Workspace lifecycle management (create, destroy, inspect) +- Control plane interaction (agents, deployments, config) +- Local development proxy / dev mode against the workspace runtime +- Configuration management (env vars, config files, workspace templates) + +## 2. Build, Test, and Local Run + +```bash +# Build the binary to ./bin/molecule (or $GOBIN/molecule) +go build -o bin/molecule ./cmd/molecule + +# Run tests (none yet; add as commands are implemented) +go test ./... + +# Run the CLI locally (requires platform env vars — see Section 5) +./bin/molecule --help +``` + +There is no `main.go` or `cmd/molecule/main.go` yet. Creating it is the first implementation task. The module path will be auto-detected from `go.mod`. + +## 3. Go Module Conventions + +**Module path:** `github.com/Molecule-AI/molecule-cli` (from `go.mod`) + +**Dependency management:** +- Use `go mod tidy` after adding or removing dependencies. +- Pin transitive dependencies if platform compatibility is a concern; document why in a comment. +- Do not commit generated lock files beyond `go.sum`. `go.sum` is the lock. +- Before upgrading a major dependency (especially the platform SDK), check whether the platform enforces API compatibility constraints (`docs/development/constraints-and-rules.md`). + +**go.sum hygiene:** Run `go mod tidy` and `go mod verify` in CI. A dirty `go.sum` (extra entries, missing checksums) is a CI failure. + +## 4. Release Process + +Releases are fully automated via GoReleaser + GitHub Actions. You do not need to run GoReleaser locally. + +**To cut a release:** + +```bash +# 1. Pull and ensure you're on main with a clean history +git checkout main && git pull + +# 2. Tag with a semantic v prefix; push the tag +git tag v0.1.0 +git push origin v0.1.0 +``` + +The GitHub Actions workflow (`.github/workflows/release.yml`) triggers on tags matching `v*`. GoReleaser builds the binary for the configured targets and creates a GitHub Release automatically. + +**Rules:** +- Tags must match `v*` (e.g., `v0.1.0`, not `0.1.0`). +- Do not push release tags from branches; always from a clean main. +- If the release build fails, fix forward: do not delete remote tags. Create a corrected tag (e.g., `v0.1.1`) and push it. +- Changelog is generated by GoReleaser from conventional commits. Use conventional commit messages on merged PRs. + +## 5. Platform Integration Notes + +The CLI will interact with the Molecule AI platform via two interfaces: + +**Control plane API:** REST/HTTP endpoints for agent management, workspace lifecycle, and deployment config. Endpoint base URL is configured via environment variable. + +**Workspace runtime:** The local or hosted runtime that executes agent workloads. The CLI proxies or delegates to this runtime in dev mode. + +**Required environment variables:** + +| Variable | Description | Required | +|---|---|---| +| `MOLECULE_API_URL` | Control plane API base URL | Yes | +| `MOLECULE_RUNTIME_URL` | Workspace runtime URL | For dev/proxy mode | +| `MOLECULE_API_TOKEN` | API authentication token | Not yet; MVP has no auth per platform rules | + +> **Note:** Per platform constraints (`docs/development/constraints-and-rules.md`), this is an MVP repo with no auth. The CLI should not emit or accept bearer tokens unless the platform constraints doc is updated. + +**Platform docs to read before touching auth or secrets:** +- `docs/development/constraints-and-rules.md` +- `docs/runbooks/saas-secrets.md` (before rotating any secrets) + +## 6. CLI Design Conventions + +**Command structure:** Follow `kubectl` / `gh` patterns. Structure is: + +``` +molecule [flags] +``` + +Examples: +``` +molecule workspace create +molecule workspace list +molecule agent inspect +``` + +**Error output style:** +- Errors go to stderr. Always. +- Format: `[resource] [verb]: [specific error]` — not a stack trace. +- Exit code 1 for errors; 0 for success; 2 for usage/flag errors. +- Wrap platform API errors with the CLI context so they are actionable. + +**Flag conventions:** +- Global flags ( `--output`, `--verbose`, `--config`) come before subcommands. +- Boolean flags use `--flag` / `--no-flag` inversion where appropriate. +- Environment variable overrides: prefer it. Flag → env var → default. +- No single-letter flags unless they are universally understood (`-h`, `-v`, `-o`, `-f`). + +## 7. Known Issues + +See `known-issues.md` at the repo root for the full tracked list. + +**Policy:** File a GitHub issue before patching silently. Do not merge a workaround without a linked issue. + +## 8. Early / Stub Repo Status + +This repo was initialized 2026-04-16. The following is needed before a functional CLI exists: + +- [ ] `cmd/molecule/main.go` — entry point with root command +- [ ] Root command and global flags (`--verbose`, `--output`, `--config`) +- [ ] `workspace create`, `workspace list`, `workspace delete` subcommands +- [ ] `agent inspect`, `agent list` subcommands +- [ ] Control plane API client (initialized with `MOLECULE_API_URL`) +- [ ] Workspace runtime client (for dev/proxy mode) +- [ ] Configuration file (e.g., `~/.config/molecule/cli.yaml`) — workspace template per platform rules +- [ ] Unit tests for core command logic +- [ ] `molecule init` (bootstrap local workspace config) + +**Platform constraint reminders (from `constraints-and-rules.md`):** +- Postgres is the source of truth. CLI commands that mutate state ultimately write to Postgres via the control plane. +- Bundles must never contain secrets. Any config templating must enforce this. +- Workspace templates are generic by default. Platform-provided templates are used; do not bake environment-specific values into templates. + +--- + +## Platform Conventions (Inherited) + +These apply to all platform repos including this one: + +- **Cron discipline:** Read `cron-learnings` before reviewing PRs. After each triage cycle, write a 1-line reflection to `.claude/per-tick-reflections.md`. +- **CLAUDE.md / PLAN.md sync:** PRs that touch `CLAUDE.md` or `PLAN.md` are always noteworthy — review them carefully. +- **Secrets rotation:** Before rotating any secrets, read `docs/runbooks/saas-secrets.md`. diff --git a/known-issues.md b/known-issues.md new file mode 100644 index 0000000..4e15a04 --- /dev/null +++ b/known-issues.md @@ -0,0 +1,149 @@ +# Known Issues — molecule-cli + +Issues identified in source but not yet filed as GitHub issues (GH_TOKEN +unavailable in automated agent contexts). Each entry has: location, +symptom, impact, suggested fix. + +Format per entry: +``` +## KI-N — Short title + +**File:** `:` +**Status:** TODO comment / identified / partially fixed +**Severity:** Critical / High / Medium / Low + +### Symptom +... + +### Impact +... + +### Suggested fix +... +--- +``` + +--- + +## KI-001 — No entry point yet (`cmd/molecule/main.go` does not exist) + +**File:** `cmd/molecule/main.go` +**Status:** Not yet implemented +**Severity:** Critical + +### Symptom +The repo is initialized as a Go module but has no `cmd/molecule/main.go`. Running +`go build ./cmd/molecule` or `go run ./cmd/molecule` fails with +"package cmd/molecule: cannot find module" or "build failed". + +### Impact +The CLI is not runnable. No workspace management, agent inspection, or any other +CLI command exists. The repo is a stub. + +### Suggested fix +Implement `cmd/molecule/main.go` with a root `cobra.Command` that registers +subcommands. Wire up global flags (`--verbose`, `--output`, `--config`). +Wire `MOLECULE_API_URL` env var as the default for the API base URL. +See the stub checklist in `CLAUDE.md` Section 8. + +--- + +## KI-002 — No API client; all commands will make raw HTTP calls + +**File:** `cmd/molecule/` (no API client package yet) +**Status:** Not yet implemented +**Severity:** High + +### Symptom +There is no `internal/client/` or `pkg/api/` package. Any subcommand +implementation will need to import the platform SDK (`molecule-sdk-python`) via +a Go FFI wrapper, make raw `net/http` calls directly, or wait for a Go SDK to be +built. Neither exists yet. + +### Impact +Subcommand implementations will either duplicate HTTP client logic or require +architecting a clean API client interface before the first command can be +meaningfully built. + +### Suggested fix +Before implementing subcommands, define `internal/api/client.go` with a +`Client` struct wrapping `*http.Client`. Implement methods for workspace and +agent operations. Add a `ClientOption` functional options pattern for +configuring base URL and auth. Document the API endpoints in `docs/` as they +are implemented. + +--- + +## KI-003 — `go.sum` may contain entries from non-release toolchains + +**File:** `go.sum` +**Status:** Identified +**Severity:** Low + +### Symptom +The `go.sum` file was generated during initial module setup. It may contain +checksum entries for transitive dependencies pulled from toolchains or +platforms not intended for the release build (e.g. `linux/arm64` on an `amd64` +host). GoReleaser targets specific platforms and any spurious `go.sum` +entries may cause CI divergence or checksum mismatches. + +### Impact +`go mod verify` in CI may fail if `go.sum` has extra entries not in the + lock file. Additionally, if the module path (`github.com/Molecule-AI/molecule-cli`) + is referenced via `replace` directives from other repos, those references may +persist stale entries. + +### Suggested fix +Run `go mod tidy` on a clean checkout from `main` and commit only the +resulting `go.sum`. Add `go mod verify` to CI as a lint step. Ensure +`.goreleaser.yaml` specifies exact Go version matching CI. + +--- + +## KI-004 — GoReleaser config may not be aligned with go.mod module path + +**File:** `.github/workflows/release.yml` +**Status:** Not verified +**Severity:** Medium + +### Symptom +The GoReleaser workflow is wired up but has not been tested with a real tag. +The `gomod.alphaSettings` or `builds[].dir` settings in `.goreleaser.yaml` +(if it exists) may not correctly resolve the module root. A real `v*` tag +push could produce an empty release or a binary with the wrong name. + +### Impact +The first release may silently fail or produce a malformed artifact that is +not usable by platform operators. + +### Suggested fix +Before the first release, test goreleaser locally with `goreleaser check` +and `goreleaser snapshot --clean`. Verify the binary name, module path, and +target OS/arch match expectations. Ensure `goreleaser.yaml` `builds[].dir` +is set to `.` (repo root) since the main package is at `cmd/molecule`. + +--- + +## KI-005 — No integration test for the full CLI lifecycle + +**File:** `tests/` (does not exist) +**Status:** Not yet implemented +**Severity:** Medium + +### Symptom +There are no tests at all (per `go test ./...` — no packages match). +As subcommands are built, there is no test harness for end-to-end CLI testing +(e.g. `molecule workspace create --name test --output json` → verify JSON output). + +### Impact +Each subcommand will be shipped without regression protection. Manual testing +is required for every release. The absence of a `tests/` directory also means +there is no fixture for CLI integration testing with recorded API responses. + +### Suggested fix +Add `tests/` with: +- `cmd/molecule/molecule_test.go` — table-driven tests for each subcommand + using `exec.Command("molecule", ...)` against a built binary +- Use `molecule-sdk-python` fixture server or recorded API responses for + offline testing +- Add `go test ./...` to CI; require >0 test packages before merge