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 <noreply@anthropic.com> * 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 <noreply@anthropic.com> --------- Co-authored-by: Molecule AI SDK-Dev <sdk-dev@agents.moleculesai.app> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
molecule-ai[bot]
GitHub
parent
898d792888
commit
5e5ec063bf
34
.claude/settings.json
Normal file
34
.claude/settings.json
Normal file
@ -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
|
||||||
|
}
|
||||||
152
CLAUDE.md
Normal file
152
CLAUDE.md
Normal file
@ -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 <resource> <verb> [flags]
|
||||||
|
```
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
```
|
||||||
|
molecule workspace create
|
||||||
|
molecule workspace list
|
||||||
|
molecule agent inspect <agent-id>
|
||||||
|
```
|
||||||
|
|
||||||
|
**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`.
|
||||||
149
known-issues.md
Normal file
149
known-issues.md
Normal file
@ -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:** `<path>:<line>`
|
||||||
|
**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
|
||||||
Loading…
Reference in New Issue
Block a user