chore: add AGENTS.md, commit hooks, coverage thresholds, deadcode detection, spec templates

Author: Patel230

.githooks/prepare-commit-msg

@@ -0,0 +1,23 @@
+#!/bin/sh
+# Auto-strip Co-authored-by trailers and enforce conventional commits
+COMMIT_MSG_FILE=$1
+COMMIT_SOURCE=$2
+
+# Skip merge commits, amend, etc.
+if [ "$COMMIT_SOURCE" = "merge" ] || [ "$COMMIT_SOURCE" = "squash" ]; then
+  exit 0
+fi
+
+# Strip Co-authored-by lines
+sed -i.bak "/^Co-authored-by:/d" "$COMMIT_MSG_FILE" 2>/dev/null || \
+  sed -i  "/^Co-authored-by:/d" "$COMMIT_MSG_FILE"
+
+# Remove trailing blank lines
+sed -i.bak -e :a -e "/^
+*$/{$d;N;ba" -e "}" "$COMMIT_MSG_FILE" 2>/dev/null || \
+  sed -i  -e :a -e "/^
+*$/{$d;N;ba" -e "}" "$COMMIT_MSG_FILE"
+
+# Clean up backup files
+rm -f "${COMMIT_MSG_FILE}.bak"
+

.github/workflows/ci.yml

@@ -35,7 +35,7 @@ jobs:
           python -m pip install --upgrade pip
           pip install -e ".[dev]"
       - name: pytest
-        run: pytest --strict-markers --tb=short
+        run: pytest --strict-markers --tb=short --cov=hawk --cov-report=term-missing --cov-fail-under=30
 
   lint:
     name: lint (ruff)

AGENTS.md

@@ -0,0 +1,44 @@
+# AGENTS.md — hawk-sdk-python
+
+Python SDK for the Hawk daemon API. Provides an idiomatic Python client for chat, streaming, sessions, and stats.
+
+## Design Principles
+
+- **Thin wrapper** — maps directly to the hawk daemon HTTP API
+- **Type-hinted** — full type annotations for IDE support
+- **Zero dependencies** — only `requests` and `typing_extensions`
+
+## Build & Test
+
+```bash
+pip install -e ".[dev]"          # Install with dev deps
+pytest                           # Run tests
+pytest --cov=hawk --cov-report=term-missing  # Coverage
+ruff check .                     # Lint
+ruff format .                    # Format
+mypy .                           # Type check
+```
+
+## Architecture
+
+- `hawk/client.py` — Main `HawkClient` class
+- `hawk/models.py` — Pydantic models for API responses
+- `hawk/errors.py` — Typed error classes (`HawkAPIError`, etc.)
+- `hawk/discovery.py` — Auto-discover running hawk daemon
+- `hawk/memory_tools.py` — Memory graph operations
+- `tests/` — Test suite with mocked HTTP responses
+
+## Conventions
+
+- Python 3.10+
+- `ruff` for linting and formatting (enforced in CI)
+- Type annotations required on all public APIs
+- Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`
+- No `Co-authored-by:` trailers
+- `pytest` for testing, `httpretty` for HTTP mocking
+
+## Common Pitfalls
+
+- `HawkClient` uses context manager (`with` statement) for cleanup
+- Discovery scans localhost ports — tests must mock this
+- `Retry-After: 0` is valid — respect it, don't retry immediately

Makefile

@@ -95,3 +95,7 @@ clean: ## Remove build artefacts and caches.
 
 help: ## Show this help.
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: hooks
+hooks:
+	git config core.hooksPath .githooks

plans/SPEC-TEMPLATE.md

@@ -0,0 +1,59 @@
+# Feature Specification: [Feature Name]
+
+**Status:** Draft | In Review | Approved | Implemented
+**Author:** [Your Name]
+**Date:** [YYYY-MM-DD]
+**Repos affected:** [list repos]
+
+## Problem Statement
+
+[What problem does this solve?]
+
+## Proposed Solution
+
+[High-level approach]
+
+## Design Details
+
+### API Changes
+
+[New endpoints, types, interfaces]
+
+### Data Model Changes
+
+[Schema changes, migrations]
+
+### UI Changes
+
+[Screens, components, flows]
+
+## Alternatives Considered
+
+[What else was considered and why rejected]
+
+## Implementation Plan
+
+### Phase 1: [Name]
+- [ ] Task 1
+- [ ] Task 2
+
+### Phase 2: [Name]
+- [ ] Task 1
+- [ ] Task 2
+
+## Testing Strategy
+
+- Unit tests: [what to test]
+- Integration tests: [what to test]
+- E2E tests: [what to test]
+
+## Risks & Mitigations
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| [risk] | [high/med/low] | [mitigation] |
+
+## References
+
+- [Link to related docs, issues, PRs]
+