Develop to main

.editorconfig

@@ -0,0 +1,13 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+
+[*.go]
+indent_style = tab
+
+[*.{md,yml,yaml}]
+indent_style = space
+indent_size = 2

.gitattributes

@@ -0,0 +1,7 @@
+# Normalize text files and enforce LF where required
+* text=auto
+
+# Always use LF line endings for source/docs/scripts that are sensitive to EOLs
+*.go text eol=lf
+*.md text eol=lf
+*.sh text eol=lf

.github/workflows/ci.yml

@@ -0,0 +1,109 @@
+name: CI
+
+on:
+  push:
+    branches: [ develop, main, master ]
+  pull_request:
+    branches: [ '**' ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ ubuntu-latest, macos-latest, windows-latest ]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Print Go version
+        run: go version
+
+      - name: Install ripgrep (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ripgrep
+
+      - name: Install ripgrep (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          brew update
+          brew install ripgrep
+
+      - name: Install make and ripgrep (Windows)
+        if: runner.os == 'Windows'
+        shell: bash
+        run: |
+          choco install -y make ripgrep
+          echo "make version:"; make --version || true
+          echo "rg version:"; rg --version || true
+
+      - name: Print Go env
+        run: go env
+
+      - name: Tidy
+        shell: bash
+        run: make tidy
+
+      - name: lint (includes check-go-version)
+        shell: bash
+        run: |
+          set -o pipefail
+          make lint 2>&1 | tee lint.log
+
+      - name: Assert lint order (check-go-version before golangci-lint)
+        shell: bash
+        run: |
+          test -f lint.log || { echo "lint.log missing"; exit 1; }
+          L_CHECK=$(rg -n "^check-go-version: OK" -N lint.log | head -1 | cut -d: -f1)
+          L_GCL=$(rg -n "^golangci-lint version" -N lint.log | head -1 | cut -d: -f1)
+          if [ -z "$L_CHECK" ]; then echo "Missing 'check-go-version: OK' line in lint.log"; exit 1; fi
+          if [ -z "$L_GCL" ]; then echo "Missing 'golangci-lint version' line in lint.log"; exit 1; fi
+          if [ "$L_CHECK" -ge "$L_GCL" ]; then
+            echo "Ordering incorrect: 'check-go-version: OK' occurs at line $L_CHECK, after golangci-lint version at line $L_GCL"; exit 1;
+          fi
+          echo "Lint order OK: check-go-version runs before golangci-lint"
+
+      - name: Upload lint.log artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: lint-${{ matrix.os }}
+          path: lint.log
+          if-no-files-found: error
+
+      - name: Tools path hygiene
+        shell: bash
+        run: make check-tools-paths
+
+      - name: Verify tools manifest commands
+        shell: bash
+        run: make verify-manifest-paths
+
+      - name: Test
+        shell: bash
+        run: make test
+
+      - name: Test clean-logs guard
+        shell: bash
+        run: make test-clean-logs
+
+      - name: Build
+        shell: bash
+        run: make build
+
+      - name: Build tools
+        shell: bash
+        run: make build-tools

.gitignore

@@ -0,0 +1,31 @@
+agentcli
+agentcli.exe
+bin/
+logs/
+
+.goagent
+*.log
+
+# Ignore built tool binaries only; keep sources tracked
+tools/bin/**
+
+# Test reports and coverage artifacts
+# Keep the working tree clean after local test runs
+reports/
+tests/
+coverage.out
+*.coverprofile
+coverage.html
+lint.err
+lint_verify.err
+
+# Common local artifacts
+dist/
+.DS_Store
+go.work
+.idea/
+.vscode/
+# Editor swap files
+*.swp
+
+work/

.gitmodules

@@ -0,0 +1,6 @@
+[submodule ".cursor/rules"]
+	path = .cursor/rules
+	url = [email protected]:hyperifyio/go-cursor-rules.git
+[submodule "scripts"]
+	path = scripts
+	url = [email protected]:hyperifyio/go-scripts.git

.golangci.yml

@@ -0,0 +1,27 @@
+run:
+  timeout: 5m
+  issues-exit-code: 1
+  tests: true
+
+linters:
+  enable:
+    - govet
+    - gofmt
+    - errcheck
+    - staticcheck
+    - gocyclo
+    - gosimple
+
+linters-settings:
+  gocyclo:
+    min-complexity: 20
+  gofmt:
+    simplify: true
+  errcheck:
+    check-type-assertions: true
+    check-blank: true
+
+issues:
+  exclude-use-default: false
+  max-issues-per-linter: 0
+  max-same-issues: 0

CODE_OF_CONDUCT.md

@@ -0,0 +1,12 @@
+## Code of Conduct
+
+We are committed to a welcoming and inclusive community. All participants are expected to be respectful and professional.
+
+- Be kind and constructive. Assume good intent.
+- No harassment, discrimination, or exclusionary behavior.
+- Use inclusive language. Respect different backgrounds and experiences.
+- Provide actionable, empathetic feedback in reviews and discussions.
+
+If you experience or witness unacceptable behavior, please report it by opening a confidential issue or contacting the maintainers via the repository's security or contact channels.
+
+Consequences for unacceptable behavior may include temporary or permanent bans from participation at the maintainers' discretion.

CONTRIBUTING.md

@@ -0,0 +1,57 @@
+## Contributing to goagent
+
+Thank you for your interest in improving `goagent`! Contributions are welcome.
+
+### Ways to contribute
+- Report bugs and request features via the issue tracker
+- Improve documentation and examples
+- Submit pull requests for fixes and enhancements
+
+### Development setup
+- Prerequisites: Go 1.24+, `ripgrep` (rg), `golangci-lint`
+- Recommended commands from a clean clone:
+```bash
+make tidy build build-tools
+make test
+make lint
+```
+
+### Workflow
+1. Fork the repository and create a feature branch from `develop`
+2. Write tests first (unit/integration). Keep tests deterministic and offline
+3. Implement the smallest change to make tests pass; keep code clear and readable
+4. Run quality gates locally:
+```bash
+make test
+make lint
+```
+5. Open a pull request that:
+   - Explains the intent and links to the canonical GitHub issue
+   - Describes user-facing changes and risks
+   - Updates docs as needed
+
+### Coding standards
+- Go formatting: run `gofmt -s` (enforced by `make lint`)
+- Linting: `golangci-lint run` (invoked by `make lint`)
+- Avoid deep nesting; prefer early returns and clear error handling
+- Add tests for all changed behaviors; maintain or improve coverage
+
+### Tools layout conventions
+- Tool sources live under `tools/cmd/NAME/*.go`
+- Tool binaries are built to `tools/bin/NAME` (or `NAME.exe` on Windows)
+- Use `make build-tools` or `make build-tool NAME=<name>` to build
+- Validate paths and manifests locally:
+```bash
+make check-tools-paths
+make verify-manifest-paths
+```
+
+### Commit messages
+- Keep the subject concise; focus on the why, not just the what
+- Reference the issue with a full URL in either the PR description or commit body
+
+### Code of Conduct
+By participating, you agree to abide by the project Code of Conduct. See `CODE_OF_CONDUCT.md`.
+
+### Getting help
+If you are blocked while contributing, open a draft PR or an issue with details. We'll help you move forward.