chore(repo): bootstrap repo skeleton and hygiene by cjimti · Pull Request #9 · plexara/plexara-agents

cjimti · 2026-05-05T22:00:10Z

Closes #2. Part of #1 (project bootstrap, v0.1).

This is phase 1 of 7 in the v0.1 bootstrap. It scaffolds the repository — directory layout, hygiene files, lint/build configuration, and Dependabot — so subsequent phases can layer CI, library code, the CLI, and examples onto a known-good foundation. No Go source is added under core/ or cmd/ in this PR. Empty packages exist as .gitkeep placeholders; the Go file count is one (internal/tools/tools.go).

Summary

Module declared as github.com/plexara/plexara-agents, Go 1.26.
Dev tooling pinned through the standard //go:build tools pattern in internal/tools/tools.go so go install produces a reproducible local toolchain. go mod tidy has resolved the full set; go.sum is locked.
Repo hygiene files in place: README with badge placeholders, CONTRIBUTING with the contributor workflow, CODE_OF_CONDUCT (Contributor Covenant 2.1, adopted by reference), SECURITY with the disclosure process and supported-versions matrix.
.github/ populated with CODEOWNERS, a PR template, three issue templates (bug / feature / security-redirect), an ISSUE_TEMPLATE/config.yml that disables blank issues and surfaces Discussions and the security advisory page, and a Dependabot config covering gomod and github-actions on a weekly schedule with grouped minor/patch updates and Conventional Commit prefixes.
.golangci.yml set up with the spec's full linter set and thresholds (gocyclo=15, gocognit=20, dupl=150, nolintlint requiring explanations, revive rule list).
Makefile mirrors CI: make build, make test, make lint, make sec, make cover, make tidy, make tools, plus fmt, vet, vuln, clean, help.
.pre-commit-config.yaml installed for whitespace, EOF, YAML/JSON validation, large-file gates, mixed line endings, merge-conflict markers, and private-key detection.
.gitignore covers Go build artifacts and the local .claude/ agent state directory.

Phase mapping

This PR is the foundation. The remaining six phases each have their own ticket and branch:

Phase	Issue	Branch
1. Repo skeleton & hygiene (this PR)	#2	`feat/bootstrap-skeleton`
2. CI & release pipeline	#3	`feat/bootstrap-ci`
3. `core/event` + `core/provider`	#4	`feat/bootstrap-event-provider`
4. `core/mcp` + `core/session`	#5	`feat/bootstrap-mcp-session`
5. `core/loop` + `core/router` + `core/approval`	#6	`feat/bootstrap-loop-router-approval`
6. `cmd/ask` CLI	#7	`feat/bootstrap-ask`
7. `examples/acme-revenue` + ADR + architecture doc	#8	`feat/bootstrap-acme-example`

Files added (24)

Hygiene & docs

README.md — badges (CI, Codecov, Go Report Card, OpenSSF Scorecard, Release, License, pkg.go.dev), pre-v0.1 status callout
CONTRIBUTING.md — local dev setup, Conventional Commits, signed-commit guidance, code standards
CODE_OF_CONDUCT.md — adopts Contributor Covenant 2.1 by reference
SECURITY.md — GitHub PVR + email reporting via support@plexara.io with a [SECURITY] subject prefix, supported-versions matrix, Cosign / SBOM / SLSA verification placeholder
.gitignore — Go defaults plus .claude/

.github/

CODEOWNERS — @cjimti on everything, with extra entries on .github/, .goreleaser.yaml, .golangci.yml, core/, docs/, and the doc set
PULL_REQUEST_TEMPLATE.md — summary, linked issue, type checklist, contributor checklist, reviewer notes
ISSUE_TEMPLATE/bug.md, feature.md, security-redirect.md, config.yml
dependabot.yml — gomod + github-actions, weekly Monday 06:00 UTC, grouped minor/patch, Conventional Commit prefixes
workflows/.gitkeep — placeholder; phase 2 fills this in

Build, lint, format

go.mod, go.sum — module path, Go 1.26, dev tools resolved through internal/tools/tools.go
.golangci.yml — full linter set per spec §14.5
Makefile — CI-mirroring targets
.pre-commit-config.yaml — pre-commit hygiene hooks
internal/tools/tools.go — //go:build tools pinning of golangci-lint, goimports, govulncheck, gosec, go-licenses, syft, cosign

Layout placeholders

core/.gitkeep, cmd/.gitkeep, examples/.gitkeep, docs/prompts/.gitkeep, docs/adrs/.gitkeep

Out of scope (deferred to later phases)

GitHub Actions workflows (ci.yml, security.yml, codeql.yml, scorecard.yml, dependency-review.yml, release.yml, fuzz.yml) — phase 2 / Phase 2: CI & release pipeline #3
GoReleaser config — phase 2 / Phase 2: CI & release pipeline #3
Branch protection rules on main — manual GitHub setting, not configurable via this PR
Any Go source under core/ or cmd/ — phases 3 through 7

Notes for the reviewer

Why CC 2.1 by reference rather than inline. Standard practice in mature OSS projects. Keeps CODE_OF_CONDUCT.md short and authoritative — the canonical text always lives at contributor-covenant.org and is updated there.
Email is unified. The original spec hinted at a security@ mailbox; the only address that exists today is support@plexara.io. SECURITY.md, CODE_OF_CONDUCT.md, and the security-redirect issue template all route to it with subject-line prefixes ([SECURITY], [CONDUCT]).
Why internal/tools/tools.go already pulled in deps. Once that file imports the tool packages, go mod tidy resolves them — that is the intended outcome of the standard tools pattern. Versions in go.sum are now the local source of truth and Dependabot will keep them current.
Linter version is golangci-lint v2. The .golangci.yml schema uses version: "2" and the new linters.default: standard plus enabled list. The Makefile and tools.go import github.com/golangci/golangci-lint/v2/cmd/golangci-lint.
Empty directories. core/, cmd/, examples/, docs/prompts/, docs/adrs/, .github/workflows/ carry .gitkeep placeholders so the planned layout is visible at a glance. They get deleted as real files arrive in later phases.

Test plan

go build ./... runs clean (no packages yet, so emits the expected "matched no packages" warning and exits 0)
go mod verify reports all modules verified
go vet ./... exits 0
make help lists all targets
PR title passes Conventional Commits format (chore(repo): ...)
Branch protection (when enabled) blocks merge until a reviewer approves
After merge, phase 2 / Phase 2: CI & release pipeline #3 can branch from main and start adding workflows

Scaffolds the repository for the v0.1 bootstrap (#1): - go.mod / go.sum with Go 1.26 and pinned dev tools via internal/tools/tools.go - README, CONTRIBUTING, CODE_OF_CONDUCT (Contributor Covenant 2.1 by reference), SECURITY - .github/CODEOWNERS, PR template, issue templates (bug, feature, security-redirect, config) - Dependabot for gomod and github-actions, weekly grouped minor/patch - .golangci.yml with the spec's full linter set (gocyclo=15, gocognit=20, nolintlint with require-explanation) - Makefile (build, test, lint, sec, cover, tidy, tools, fmt, vet, vuln, clean) - .pre-commit-config.yaml (whitespace, EOF, yaml/json check, large files, mixed line endings, private key) - Directory layout placeholders for core/, cmd/, examples/, docs/{prompts,adrs}/, .github/workflows/ No Go source yet — phases 3+ land it. CI workflows land in phase 2 (#3). Closes #2.

- Switch from the //go:build tools pattern to the go.mod `tool` directive (Go 1.24+). Drop internal/tools/tools.go. Drop cosign and syft from the module graph (they are release-time tools and belong in the release workflow / GoReleaser config in phase 2). Net result: go.mod 657 -> 268 lines, go.sum 2637 -> 1088 lines. - Update Makefile to invoke pinned tools through `go tool <name>`. Remove the redundant `make tools` target. Add a `licenses` target for go-licenses. `make build` now prints a clear note when there are no Go packages yet, so contributors do not mistake the empty build for a successful one. - Update CONTRIBUTING.md: replace `make tools` instructions with `go mod tidy` plus a note that tools are invoked via `go tool`. Complete the SSH-signed-commit setup (gpg.ssh.allowedSignersFile was missing, which left signatures showing as unverified on GitHub). - README: drop speculative badges (CI, Codecov, Go Report Card, Scorecard, Release, pkg.go.dev) that would render broken until the underlying integrations exist. Keep License. Add a note about when the rest will land. - SECURITY.md: clarify that the supported-versions matrix is the policy that takes effect at v0.1.0; explicitly note that until then only `main` is supported. - .gitignore: cover vendor/ (guards against accidental `go mod vendor`), go.work / go.work.sum, and *.exe. - .golangci.yml: rename `gomodguard` to `gomodguard_v2` (deprecated in golangci-lint 2.12.0). Verified clean via `golangci-lint config verify`. - docs/adrs/0001-tool-directive-vs-tools-build-tag.md: ADR documenting the toolchain decision and its deviation from the spec at issue #1 §16.2. Issue #8 (phase 7) updated to renumber the provider ADR to 0002. Verified locally: - go mod verify -> all modules verified - go vet ./... -> clean - golangci-lint config -> verify exit 0 - make build -> exit 0 with friendly empty-tree note

cjimti added 2 commits May 5, 2026 14:36

cjimti merged commit 887d2bb into main May 5, 2026

cjimti deleted the feat/bootstrap-skeleton branch May 5, 2026 22:50

This was referenced May 6, 2026

ci(workflows): add CI, security, release, and supply-chain pipeline #10

Merged

feat(core): add core/event and core/provider packages #11

Merged

feat(core): add core/mcp and core/session packages #13

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(repo): bootstrap repo skeleton and hygiene#9

chore(repo): bootstrap repo skeleton and hygiene#9
cjimti merged 2 commits intomainfrom
feat/bootstrap-skeleton

cjimti commented May 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

cjimti commented May 5, 2026

Summary

Phase mapping

Files added (24)

Out of scope (deferred to later phases)

Notes for the reviewer

Test plan

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant