Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions .apm/commands/architecture-review.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
description: "Comprehensive architecture review: generate a ranked findings document, then address findings systematically one commit at a time"
argument-hint: "[review|address [round]]"
allowed-tools: ["Bash", "Glob", "Grep", "Read", "Write", "Edit", "Task"]
---

# Architecture Review Workflow

Generate a comprehensive architecture review document, or systematically address findings from a prior review.

**Arguments:** "$ARGUMENTS"

---

## Phase 1: Generate Review (`architecture-review review`)

Perform a comprehensive architecture and engineering review of the current codebase and write the output to `claude-review-architecture.md`.

### Review Dimensions

Analyse the codebase across these dimensions:

- **Inconsistencies** — mismatched patterns, duplicate logic, divergent conventions
- **Correctness** — bugs, race conditions, error handling gaps, incorrect assumptions
- **Maintainability** — coupling, cohesion, complexity, testability
- **Modern practices** — alignment with current language idioms and community standards
- **Architecture** — apply hexagonal architecture thinking to identify areas of high coupling and candidates for restructuring

### Output Format

Write findings to `claude-review-architecture.md`:

1. Executive summary
2. Findings list, each with:
- Title and affected file(s)
- Dimension(s) it falls under
- Description and recommended fix
- Priority rating (High / Medium / Low) across all dimensions
3. Ranked priority table (highest-impact findings first)

---

## Phase 2: Address Findings (`architecture-review address [round]`)

Systematically work through findings in `claude-review-architecture.md`, one commit per finding.

**Round** (optional): limits work to a labelled subset of findings (e.g. `Round-2`). Defaults to all unresolved findings.

### Workflow per Finding

1. **Plan** — read the finding and identify the minimal correct fix
2. **Baseline complexity** — record cognitive complexity before touching the file:
```bash
gocognit <file>
```
3. **Fix** — implement the change; if the correct fix lives in an upstream `github.com/dioad` repository, create a GitHub issue instead:
```bash
gh issue create --repo github.com/dioad/<repo> --title "..." --body "..."
```
4. **Verify** — run the repository's pre-completion checks before committing (e.g. `make verify`)
5. **Post-fix complexity** — record cognitive complexity after the fix:
```bash
gocognit <file>
```
6. **Commit** — one conventional commit per finding:
```
fix: <short description of finding>
```
7. **Update document** — record outcome, commit SHA, and complexity delta in `claude-review-architecture.md`

### Constraints

- Keep complexity the same or lower after each fix — do not let it increase
- Do not batch multiple unrelated findings into one commit
- Do not skip the pre-completion checks step
19 changes: 19 additions & 0 deletions .apm/instructions/git-workflow.instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
---
description: 'Git workflow rules for this repository'
applyTo: "**"
---

# Git workflow instructions

When performing Git operations in this repository, follow these rules:

1. Never push to remote repositories (`git push` is not allowed).
2. Do not use `git add -A` (or `git add .`). Stage files explicitly by path.
3. Only stage files you directly modified for the requested task.
4. Use Conventional Commits for commit messages (for example: `fix: ...`, `feat: ...`, `chore: ...`).

Recommended safety practices:

1. Do not create commits unless the user explicitly asks for a commit.
2. Do not amend commits unless explicitly requested.
3. Before committing, inspect staged changes with `git diff --cached` to confirm scope is correct.
230 changes: 230 additions & 0 deletions .apm/instructions/go-graph.instructions.md

Large diffs are not rendered by default.

83 changes: 83 additions & 0 deletions .apm/instructions/go-testing.instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
---
description: 'Cross-project Go testing instructions: testify assertions, executable examples, and Test Desiderata 2.0'
applyTo: '**/*.go'
---

# Go Testing Instructions

## Assertions: Use testify

Use `github.com/stretchr/testify` for all test assertions. Do not use bare `t.Error`, `t.Fatal`, or manual comparisons when testify covers the case.

- Use `github.com/stretchr/testify/assert` for non-fatal assertions (test continues after failure).
- Use `github.com/stretchr/testify/require` for fatal assertions (test stops immediately on failure). Prefer `require` for setup and preconditions.
- Use `github.com/stretchr/testify/mock` for mock objects when interface substitution is needed.

```go
import (
"testing"

"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)

func TestFoo(t *testing.T) {
result, err := Foo()
require.NoError(t, err)
assert.Equal(t, "expected", result)
}
```

Prefer specific assertions over generic ones (`assert.Equal` over `assert.True(t, a == b)`), as they produce clearer failure messages.

## Executable Examples

All Go code examples must be executable and written using the `func Example...` convention from the `testing` package. Place example functions in `*_test.go` files.

- Name examples `ExampleFunctionName`, `ExampleType_MethodName`, or `ExamplePackage` following Go conventions.
- Include an `// Output:` comment so `go test` verifies the output automatically.
- Keep examples self-contained and minimal — they serve as documentation.

```go
func ExampleGreet() {
fmt.Println(Greet("world"))
// Output:
// hello, world
}
```

Do not write example code in comments, README snippets, or prose without a corresponding runnable `func Example...` counterpart in a `_test.go` file.

## Test Desiderata 2.0

Write tests that satisfy the properties from [Test Desiderata 2.0](https://coding-is-like-cooking.info/2025/12/test-desiderata-2-0/). These are grouped by the outcome they support.

### Predict Success in Production

- **Sensitive to Behaviour** — tests must detect functional regressions. Test observable outputs and side effects, not internal implementation details.
- **Sensitive to Execution Qualities** — where relevant, cover non-functional concerns such as latency bounds, concurrency safety (`-race`), and resource cleanup.

### Fast Feedback

- **Minimal Data** — use the smallest dataset that exercises the behaviour. Avoid large fixtures when a single representative value will do.
- **Run in Any Order** — tests must be fully independent. Never rely on global state left by another test; use `t.Cleanup` or reset state explicitly.
- **Run in Parallel** — call `t.Parallel()` in tests that are safe to run concurrently. Design tests to be parallelisable by default.

### Low Total Cost of Ownership

- **Automated** — every test must run via `go test ./...` with no manual steps.
- **Deterministic** — tests must produce the same result on every run. Eliminate time dependencies, random seeds, and environment-specific assumptions.
- **Diagnosable** — a failing test must clearly communicate what went wrong. Use testify's descriptive messages and `t.Run` subtests with meaningful names so failures are easy to locate and understand.
- **Easy to Read** — test code is documentation. Prefer readability over brevity. Use table-driven tests and `t.Run` to express intent clearly.
- **Easy to Update** — write tests against the public API and observable behaviour, not private functions or implementation internals, so refactoring does not require rewriting tests.
- **Easy to Write** — reduce friction: shared helpers go in `testdata` or helper functions marked with `t.Helper()`. Reuse setup with `t.Cleanup` rather than duplicating teardown.
- **Insensitive to Code Structure** — tests must not break when the code is refactored without changing behaviour. Avoid testing private functions directly.

### Support Ongoing Code Design Change

- **Composable** — structure tests so subtests and helpers can be combined without duplication.
- **Documents Intent** — test names and assertions should describe what the code is supposed to do, not how it does it. A reader should understand expected behaviour from the test alone.
- **Durable** — write tests that remain valid as the product evolves. Avoid asserting on incidental details that are likely to change.
- **Necessary** — every test must guide a development decision or prevent a real regression. Delete tests that duplicate coverage without adding signal.
- **Organized** — place test files alongside the code they test. Use `_test.go` suffix. One test file per source file is a reasonable default.
- **Positive Design Pressure** — if a piece of code is hard to test, treat that as a design signal. Refactor toward testable, decoupled interfaces rather than reaching for mocks of concrete types.
45 changes: 45 additions & 0 deletions .apm/instructions/project-checks.instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
---
description: 'Required pre-completion checks and project-specific guidelines for connect'
applyTo: "**"
---

# Pre-completion Checks

Before a task is marked as complete, run:

```bash
make verify
```

This automates: `go generate ./...`, `go build .`, `go vet ./...`, `go test -race ./...`, and `shellcheck -o all` on shell scripts. All steps must pass.

# PR Review Workflow

## Finding the PR for the Current Branch

```bash
gh pr view --json number --jq .number
gh pr view
```

## Workflow for Addressing Review Comments

1. Fetch unresolved comments for the current branch's PR
2. Analyze each comment
3. Make code changes to address the issues
4. One commit per comment or related group of issues
5. Run `make verify`
6. Push when all checks pass

## Commit Message Format for Review Fixes

```
fix: address PR {PR_NUMBER} review comments on {topic}

This commit addresses {N} unresolved review comments:

1. {Comment title} (line {X} of {file}.go)
- {Description of fix}

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
```
Loading
Loading