From 9c9d65633455808981a7cc2e4c1ab2ab5639cad6 Mon Sep 17 00:00:00 2001 From: Lakshman Patel Date: Wed, 5 Aug 2026 07:25:55 +0530 Subject: [PATCH 1/3] chore(docs): remove unreferenced stale plans/audits and fix dangling links --- CODE_AUDIT_REPORT.md | 219 -------- docs/COMPARISON-WITH-TOP-CODING-AGENTS.md | 513 ------------------ docs/architecture/README.md | 3 - .../hawk-contract-migration-inventory.md | 187 ------- .../hawk-eyrie-engine-migration.md | 130 ----- .../session-migration-inventory.md | 120 ---- .../verification-status-2026-07-13.md | 251 --------- docs/icon-survey.md | 93 ---- docs/monorepo-analysis.md | 358 ------------ docs/plans/PR_BODY.md | 52 -- docs/plans/Y0-CALL-SITE-INVENTORY.md | 77 --- docs/plans/YEAR-0-ACTIVE.md | 1 - .../architecture-upstream-release-plan.md | 209 ------- .../ecosystem-architecture-remediation.md | 133 ----- .../plans/hawk-contracts-migration-backlog.md | 1 - docs/plans/z-ai-proper-implementation.md | 337 ------------ internal/testaudit/docs_audit_test.go | 1 - plans/THEMING-ENHANCEMENT-PLAN.md | 154 ------ 18 files changed, 2839 deletions(-) delete mode 100644 CODE_AUDIT_REPORT.md delete mode 100644 docs/COMPARISON-WITH-TOP-CODING-AGENTS.md delete mode 100644 docs/architecture/hawk-contract-migration-inventory.md delete mode 100644 docs/architecture/hawk-eyrie-engine-migration.md delete mode 100644 docs/architecture/session-migration-inventory.md delete mode 100644 docs/architecture/verification-status-2026-07-13.md delete mode 100644 docs/icon-survey.md delete mode 100644 docs/monorepo-analysis.md delete mode 100644 docs/plans/PR_BODY.md delete mode 100644 docs/plans/Y0-CALL-SITE-INVENTORY.md delete mode 100644 docs/plans/architecture-upstream-release-plan.md delete mode 100644 docs/plans/ecosystem-architecture-remediation.md delete mode 100644 docs/plans/z-ai-proper-implementation.md delete mode 100644 plans/THEMING-ENHANCEMENT-PLAN.md diff --git a/CODE_AUDIT_REPORT.md b/CODE_AUDIT_REPORT.md deleted file mode 100644 index a79d9454..00000000 --- a/CODE_AUDIT_REPORT.md +++ /dev/null @@ -1,219 +0,0 @@ -# hawk-eco Code Audit Report - -**Branch:** `feat/code-audit-improvements` -**Base:** `bfd5654` (main) -**Date:** 2026-08-03 -**Scope:** `internal/` (~387K lines Go, 1,820 files), `cmd/` (372 files), `external/*` submodules (reference-only) -**Method:** automated tooling (golangci-lint, go vet, staticcheck, govulncheck, go test -race) + manual deep review of all critical paths + cross-checks against research literature and the 2026 competitor landscape. Every finding was verified against source; claims that could not be verified are marked. - ---- - -## 1. Executive summary - -hawk-eco is in unusually good health for a codebase of this size: - -- **0** golangci-lint issues, **0** go vet issues, **0** reachable vulnerabilities (govulncheck), **1** trivial staticcheck finding -- Full test suite **passes**; engine packages average **~87% coverage**; sandbox/auth 74–78% -- The security architecture is genuinely strong where it matters most: fail-closed Docker-only execution, cap-drop/no-new-privileges/read-only containers, keychain credential storage, constant-time daemon auth, atomic session persistence - -However, the audit found **1 critical, 12 high, ~20 medium, and ~30 low** findings. The dominant themes: - -1. **Built-but-unwired safety infrastructure** — panic recovery exists but is never installed; the self-improvement memory loop never persists; budget tracking exists but is never fed. -2. **Dead subsystems shipping in production** — `engine/async` (0% coverage, 2 confirmed bugs), `engine/docs` (~2,000 lines, zero importers), `MessageBus` (700 lines), approval gate, composio stub. -3. **Fail-open trust edges** — project-controlled `.agents/runtime.jsonc` executes arbitrary shell as root at image build time; HTTP decision hooks fail open silently; bash subprocesses inherit API-key env vars. -4. **Performance regressions in hot paths** — O(N) re-embedding per codegraph query, full-transcript deep clone per turn, full-prefix TUI re-render per chunk, per-call regexp compilation. - ---- - -## 2. Baseline (Phase 1) results - -| Tool | Result | -|---|---| -| `golangci-lint run ./internal/... ./cmd/...` | **0 issues** | -| `go vet ./internal/... ./cmd/...` | **clean** | -| `govulncheck ./...` | **0 called vulnerabilities** (1 in a required module, not reachable) | -| `staticcheck` | 1 finding: unused `getKeys` in `internal/engine/code/coverage_extra_test.go:131` | -| `go test ./internal/... ./cmd/...` | **all pass** | -| Coverage (critical pkgs) | engine 61–97%, sandbox 74.7%, auth 77.5%; **`engine/async` 0%** | -| Code smells | 14 files with TODO/FIXME, 9 `panic(`, 5 `os.Exit`, 71 bare `go func(` | - ---- - -## 3. Findings - -Severity scale: **CRITICAL** (crash/data loss/RCE), **HIGH** (security boundary or functional break), **MEDIUM** (correctness/reliability/race), **LOW** (hygiene/performance). - -### 3.1 CRITICAL - -**C1. No panic recovery anywhere in the production binary** -- `cmd/hawk/main.go` — `Execute()` has no `recover()`. `cmd/errors.go:33` (`panicRecovery`) and `internal/crash/crash.go` are **dead code** — zero production callers (verified by grep). -- `internal/crash/crash.go:17-18` states explicitly: *"Do NOT call this from cmd/hawk yet — wiring into the binary entry point is a future wave."* -- **Impact:** any panic in a background goroutine (TUI render, spinner at `cmd/chat_tools.go:234`, tool execution) kills the process mid-session with no session save, no crash report, no cleanup. -- **Fix:** wrap `Execute()` in `panicRecovery(saveFn)` and install `crash.Install()` at startup. *(fixed: `panicRecovery` wraps the TUI execute path; `crash.Install()` wired in `cmd/hawk/main.go`)* - -### 3.2 HIGH - -**H1. `.agents/runtime.jsonc` → arbitrary root code execution at image build time** — `internal/sandbox/runtime_deps.go:14-67`, `container.go:154,236-238` -`runtime_extra_deps[]` becomes raw `RUN ` layers in the sandbox image; `runtime_startup_env_vars` becomes `docker run -e KEY=VALUE`. The file is project-controlled and agent-writable. A malicious repo executes attacker shell as root during `docker build` (build network unrestricted, `--cap-drop` does not apply), and the result is baked into the session image — a persistent session backdoor. -**Fix:** allowlist validation (reject `curl|wget|nc|sh|bash|python` in deps; fixed key set for env; no `PATH`/`HOME`/`LD_PRELOAD`). *(fixed: blocklisted dep terms rejected with `slog.Warn`; env validated against a fixed key set)* - -**H2. Project secrets readable + exfiltratable by default** — `container.go:143` (project rw mount), `mode.go:160-170` (`ModeAllowsNetwork`: workspace → network on), `bash.go:604-673` -Default mode mounts the whole project (incl. `.env`, credentials) rw into a container with **outbound network**. A compromised agent can exfiltrate project secrets. Strict mode denies network but is not the default. `NetworkProxy`/`BlockPrivateNetworks` exist but are never wired into production (only tests reference them). -**Fix:** make strict mode's network policy the default for workspace, or wire the blocklist; document the tradeoff. - -**H3. HTTP decision hooks fail open silently** — `internal/hooks/http_hooks.go:45-88`, `decision.go:118-142` -Every failure path (marshal, request build, client error/3s timeout, non-2xx, decode, unknown action) returns `nil`, and `ExecuteDecisionHooks` treats nil as "no opinion, proceed". No logging on HTTP errors. A downed compliance/guardrail hook → every guarded tool call silently allowed. -**Fix:** return a deny decision + `slog.Warn` on error; make fail-open an explicit config option. *(fixed: deny + `slog.Warn` by default; `FailOpen` explicit opt-in)* - -**H4. SSE generation >5 min permanently wedges the daemon** — `internal/daemon/daemon.go:215` (`WriteTimeout: 300s`), `streamSSE` `:721-777` -`WriteTimeout` is an absolute deadline; `streamSSE` ignores `fmt.Fprintf` errors (`_, _ =`) and only exits on `r.Context().Done()` or channel close — neither fires when the write deadline lapses. The handler never returns; the session stripe lock (`:580-582`) and global `concurrencySem` (`:551-557`) are held forever; with the default cap of 4, all subsequent `/v1/chat` requests 503 permanently. Agentic tasks routinely exceed 5 min. -**Fix:** exit the SSE loop on write error; use `http.ResponseController` for a per-write deadline that resets per flush. *(fixed: `writeSSE` reports failures, handler exits the loop; per-write deadline via `ResponseController`)* - -**H5. External SIGINT/SIGTERM/SIGHUP bypass session save** — `cmd/chat_update.go` (no `tea.InterruptMsg`/`tea.QuitMsg` cases — verified absent), Bubble Tea v2 handles both and exits without `saveSession()`; SIGHUP unhandled (default kill). -`kill -TERM`, terminal close, or ssh drop mid-run → transcript lost, temp files left. -**Fix:** handle `tea.InterruptMsg`/`tea.QuitMsg` → run the same save path as the two-stage ctrl+c; install SIGHUP handler. *(fixed: `InterruptMsg`/`QuitMsg`/SIGHUP all route through the shared quit-save path)* - -**H6. Self-improvement memory never persists (default CLI path)** — `internal/intelligence/memory/evolving.go:36-40` (`NewEvolvingMemory` never calls `Load`), `internal/engine/lifecycle/lifecycle_adapters.go:14-39` (adapter only calls `Learn`/`Retrieve`/`Format`, never `Save`) -Everything learned at session end is lost at process exit; `OnSessionStart` always returns empty guidelines. The Reflexion-style loop is a **no-op** in the shipped CLI. -**Fix:** `Load()` in constructor, `Save()` after `Learn` (debounced), test the round-trip. *(fixed: `Load` in constructor, atomic `Save` after `Learn`, round-trip test)* - -**H7. Budget enforcement is split-brain** — `internal/engine/lifecycle/limits.go:14` (`MaxCostUSD` "default: from MaxBudgetUSD" — never implemented), `:86` (`IsExceeded` checks `MaxCostUSD` only), `RecordCost`/`RecordTokens` have **zero production callers** (verified by grep); production budget flows through `Session.SetMaxBudgetUSD` and enforcement at `stream.go:515`. `VibeLimits` sets `MaxCostUSD: 5.0` with `MaxBudgetUSD: 0` (limits.go:147-156) — inconsistent. -**Fix:** fallback `MaxCostUSD = MaxBudgetUSD` when unset; wire `RecordCost` into the stream cost accounting; make `VibeLimits` consistent. *(fixed: `MaxCostUSD` falls back to `MaxBudgetUSD`; accessors mutex-protected (M1); cost synced from the session cost accumulator)* - -**H8. Codegraph semantic search is O(N) full re-embedding per query** — `internal/codegraph/embeddings_cgo.go:13-57`, `tool/codegraph.go:482` -Every `SemanticSearch`/`HybridSearch` `SELECT`s all nodes then recomputes `GenerateEmbedding(n)` per node (hash-based, uncached), then cosine-compares. On 100k-node repos this is seconds per tool call. The precomputed `CodeVectorStore` (`vector_store.go:122-239`) exists but is unused by `SemanticSearch` (dead duplication; itself brute-force O(N²) sort, no locks). -**Fix:** `CodeGraph.embeddingFor` memoizes embeddings in a bounded cache (200k entries, content-hash key covering every field `extractFeatures` reads; full reset when full — far cheaper than recomputing per query). `SemanticSearch` now goes through the cache; repeated queries and unchanged nodes skip recomputation. 3 new tests (memoization, content invalidation, bound). *(fixed)* - -**H9. Mission retry loop is structurally broken; failures report success** — `internal/multiagent/mission.go:158,238-258`, `worker.go:206`, `graph.go:80-90`, `cmd/mission.go:134-136` -`feature.Branch` is deterministic (`hawk-mission//`); `git worktree add -b` fails on retry 2+ because attempt 1's branch survives worktree removal — every retry fails, branch leaks. `runFeatureSet`/`RunWaves` return `nil` unconditionally → `hawk mission` **exits 0 when all features fail** (CI sees green). -**Fix:** the retry loop now rewrites `feat.Branch` to `/attempt-N` before every worker call (unique per attempt); `createWorktree` falls back to checking out an existing-but-unchecked-out branch (leaked branch or validation reuse); `removeWorktreeDetached` deletes the branch after removing the worktree (best-effort); `cmd/mission.go` returns an error — non-zero exit — when any feature failed, so CI no longer sees green on failure. *(fixed)* - -**H10. `engine/async`: goroutine leak + double-loop + missing terminal event (dead code today)** — `internal/engine/async/engine.go:93-106`, `:49-56`, `event.go:146`, `engine.go:128-146` -`Stop()` cancels ctx but the loop is parked in `subQ.Next()` (`<-sq.notify`) → **leak on every stop**; `Start()` after `Stop()` spawns a second loop draining the same queue (double processing); on stream error `EventDone` is never emitted → consumers hang; `toAsyncEvent` has no default for `compact_start`/`blast_radius` events → zero-value garbage events; `ReplyTo` contract is unfulfilled; subscribers can't unsubscribe. -**Fix:** rewritten engine: `Stop()` cancels a loop ctx and joins via WaitGroup (bounded wait); `Start` after `Stop` spawns one fresh loop; single-threaded loop drains the queue via non-recursive `pop()` after each notify (no stack-growth, no parked-goroutine leak); `Cancel()` aborts the in-flight turn directly (a queued cancel could never be popped while the loop is blocked inside the turn's stream); `EventDone` is always emitted (success, stream error, or canceled turn) and forwarded to `ReplyTo`; unmapped events map to `EventInfo` preserving the raw type; `EventQueue.Unsubscribe` added; full-UUID event/submission IDs. **9 tests, 88.2% coverage (was 0%), race-clean.** *(fixed)* - -**H11. `engine/docs`: ~2,000 lines shipping with zero importers** — `internal/engine/docs/` (docgen.go, doc_updater.go, external_docs.go) -Verified: no file outside the package references it. Within it: multi-line doc comments truncated to last line (doc_updater.go:350-368), `OldDoc` populated from *new* content (`:56,:87`), false-positive machine for capitalized words (`:522-539`), parser chokes on nested parens (`:330`), `ExternalDocs.Cache` never written (`external_docs.go:77`), methods of generic types dropped (docgen.go:938-951). -**Fix:** either wire to a `hawk docs` command or delete; at minimum fix the top-3 bugs. *(fixed: deleted — dead since f0aa8fd, no importers, six known bugs; recoverable from git history if ever wanted)* - -**H12. Bash tool subprocesses inherit API-key env vars** — `internal/tool/task_tools.go:80`, `bash.go` (`exec.CommandContext` with no `cmd.Env` → full `os.Environ()`) -Guard regexes (bash.go:102-105) block obvious dump patterns but are trivially bypassed (`python3 -c "import os;print(os.environ['ANTHROPIC_API_KEY'])"`). Keys are readable by anything the agent runs. -**Fix:** strip provider key env vars (or pass a scrubbed env) when spawning agent commands. *(fixed: agent subprocesses spawn with scrubbed env — `internal/env/scrub.go` builds the allowlist once from `ScrubSet`)* - -### 3.3 MEDIUM - -| ID | Finding | Location | -|---|---|---| -| M1 | Data race on `LimitTracker.limits` accessors (read/write without mutex) while daemon/multiagent goroutines call `SetMaxTurns` concurrently | `internal/engine/lifecycle/limits.go:129-132` *(fixed: mutex-protected accessors, covered by `limits_test.go`)* | -| M2 | `ParseAndApplyMemoryOps` swallows all errors (nil bridge, discarded `bridge.Remember`, malformed JSON); 0% coverage; runs in background goroutine | `sleeptime_ops.go:25-35`, `stream.go:626` *(fixed: returns `error` — `ErrNoMemoryOps`, wrapped parse/remember errors via `errors.Join`, nil-bridge error; call site logs `slog.Warn`; 7 new tests)* | -| M3 | `SkillDistillerAdapter` returns nil on error — "not configured" and "failed" indistinguishable | `lifecycle_adapters.go:50-52,77-80` *(fixed: `Retrieve` logs `slog.Warn` with the `Search` error)* | -| M4 | Cost metrics use fabricated session IDs (`"session_"+UnixNano`) instead of the real session ID | `lifecycle.go:158-160` *(fixed: `OnSessionEnd` reads the real ID via `Session.SessionID()` — added in `execution_graph_observations.go`; nil-getter falls back to empty)* | -| M5 | `MissionApprovalGate` is dead code (zero production callers); workers auto-approve everything incl. arbitrary bash; `sessionApproved` map would race when wired | `multiagent/approval.go:110-144`, `worker.go:61-66` *(fixed: wired into production — `Config.ApprovalGate` consulted by the worker permission fn; `Check(ctx, toolName, summary)` classifies bash/network/web actions as risky; `sessionApproved` mutex-protected)* | -| M6 | Validation-worker cleanup regressed (cancellable ctx kills `git worktree remove` → permanent leak) | `multiagent/worker.go:144` *(fixed: detached-context cleanup + branch deletion)* | -| M7 | Oversized MCP response (>1MB scanner cap) silently kills the client connection; server child stays alive; no recovery | `internal/mcp/mcp.go:95,167-179` *(fixed: dead-server flag marks the connection on readLoop end, kills the child process, and `callWithTimeout` fails fast)* | -| M8 | `Composio.ExecuteTool` returns fake success (`Success: true` echoing params); agents would report unexecuted actions | `internal/composio/composio.go:147-177` *(fixed: package deleted — unwired stub, zero importers; provider implementations belong in `external/eyrie` per the architecture note; recoverable from git history)* | -| M9 | In-memory `Tracer` accumulates spans unboundedly (daemon lifetime); `Disable()` doesn't stop recording | `internal/observability/oteltrace/trace.go:45-59,112-116` *(fixed: `StartSpan` checks `enable`, buffer capped at 10k spans; dropped spans stay functional)* | -| M10 | `diffsandbox.absPath` is lexical-only; symlinked intermediate components escape the sandbox root | `internal/diffsandbox/sandbox.go:419-435` *(fixed: component-wise walk with `Lstat` — symlinks resolved and containment-re-checked against the resolved root, dangling symlinks rejected; covers macOS `/var → /private/var`)* | -| M11 | `PolicyManager` defaults to `DecisionAllow` — stated deny-by-default posture not reflected | `internal/sandbox/manager.go:48` *(fixed: default is `DecisionDeny`; project policy takes precedence with global filling gaps; reload no longer resets to allow)* | -| M12 | userns remap conditional; without it container runs as root with rw project mount; no `--user` fallback | `container.go:33-40,149-153` *(fixed: `--user :` appended when userns remap is unavailable)* | -| M13 | Host-side file tools: check-then-open symlink TOCTOU; name-based sensitivity (`secrets.txt` allowed) | `internal/tool/file_read.go`, `file_write.go`, `safety.go:251+` *(fixed: resolve-then-revalidate + `os.SameFile` fd guard; writes land at the resolved parent; `blockedBasenames` covers secrets/credential files; symlink-escape tests added)* | -| M14 | Per-call `regexp.MustCompile` in hot paths (5 sites) | `internal/feature/eval/filters.go:13-32`, `tool/spec_checklist.go:119-149`, `tool/ticket_compliance.go:62`, `feature/fingerprint/project_conventions.go:180-181` *(fixed: all hoisted to package-level vars)* | -| M15 | Full-transcript deep clone per access in `RawMessages()` — quadratic over session length | `internal/engine/persistence_service.go`, callers `context_governor.go:120-148` *(fixed: hot per-turn reads use the read-only, non-retaining `RawMessagesView()` (no clone); `RawMessages` keeps its deep-copy snapshot contract)* | -| M16 | TUI viewport re-renders full prefix per streamed chunk — O(messages) per token | `cmd/chat_viewport_render.go` *(no change needed: render cache + incremental stream tail already make per-chunk rendering amortized O(tail); incremental-vs-full-rebuild equivalence asserted by `chat_viewport_render_test.go`)* | -| M17 | `hawk path` 1.83s wall; `MigrateProviderSecrets`→`newEyrieEngine()`+`gateway.New()` runs on **every** root command | `cmd/root.go:136`, `internal/config/eyrie_engine.go:15-17,127-133` *(fixed: migration moved off the root preamble into the chat/print/repl branches and before `runChat()`; cold commands like `hawk path` never build the engine)* | -| M18 | Unbounded TUI-side growth (history, messageQueue, messages, `toolResultExpanded`) | `cmd/chat_submit.go:51`, `chat_model.go:185` *(fixed: prompt history capped (200) via `pushHistory`, queue capped (100) via `enqueueMessage`, messages already trimmed at 500, expansion map reindexed+pruned on trim; unit tests added)* | -| M19 | Async hook goroutines never drained (`WaitAsync` has no callers) — unbounded under tool loops | `internal/hooks/hooks.go:134-156` *(fixed: session-end drains queued async hooks via `WaitAsync` with a 30s cap after `ExecuteAsync`)* | -| M20 | Legacy `Sandbox.Run` fails open when `Enabled=false` (host `bash -c`); no production callers — latent footgun | `internal/sandbox/sandbox.go:134-135` *(fixed: fails closed unless explicitly opted out via `Tier == TierOff`)* | - -### 3.4 LOW (selected) - -- Engine stream retry ignores `Retry-After`, fixed 1–3s delay (`stream.go:448`) *(fixed: `streamRetryDelay` parses a "retry in|after N[ms]" hint from the stream error (matching eyrie's retryDelayRe), honors it capped at `maxStreamRetryDelay` (60s), else falls back to the existing linear 1–N backoff; `isRetryableStreamError` broadened to surface rate-limited (429) and 503 streams for retry; added `stream_retry_test.go`) -- Deployment retry can re-select the same dead deployment (`deployment_router.go:149-150`) *(fixed in `external/eyrie` (PR #105, merged to eyrie main at `ed62022`): `selectDeploymentChoice(choices, exclude)` skips the just-failed deployment when alternatives remain; Chat/StreamChat tracks a stage-scoped `recentlyFailed` id; single-deployment stages still retry once to trip the breaker; `TestDeploymentRouterRetriesPreferDifferentEndpoint` asserts dead is tried ≤1× and healthy is reached. Hawk pins eyrie to the published pseudo-version (`026bfdd`) per the submodule/module release-parity CI gate; the fix enters Hawk on the next eyrie release tag — the submodule pointer will bump then.)* -- Substring-based retry/credit/overflow classification causes spurious retries and silent emergency-compact (`stream_helpers.go:32-40`, `retry.go:41-57`, `chat_service.go:258-264`) *(partially addressed: `isContextOverflow` tightened to match structured provider signals — `context_length_exceeded`/`context_length_error`/`exceeds the limit` — and to require a token/context qualifier alongside the legacy "too long"/"too many tokens" phrasing so ordinary "request timeout, too long" no longer spurious-compacts (reduces false positives, cannot storm); remaining substring heuristics in `retry.go` `IsRetryable` left as-is per the risk note — they are additive (more retry coverage) but traffic-driven tuning is still recommended)* -- Linux token-file write non-atomic; concurrent Set races (`auth.go:235-264`) *(fixed: token store now uses `internal/safewrite` — atomic temp-write + fsync + symlink guard)* -- Non-atomic `0o600` writes without fsync (`session/cross_session.go:376`, `memory/knowledge.go:519`) *(fixed: both now use `safewrite.WriteFile`)* -- Unbounded `EndSession` goroutine without context (`stream.go:681`) *(fixed: `IntegrationPipeline.EndSession` now takes `context.Context` and bails on a canceled context; caller passes the session ctx)* -- Sandbox image pulled by mutable tag, no digest pinning (`image.go:40-42`) *(fixed: `HAWK_SANDBOX_IMAGE_DIGEST` env pins `repo@sha256:` when set)* -- `ModeOff` disables path guard (`path_guard.go:21`) *(no change — intentional: `--sandbox off` is an explicit opt-out of all sandbox protections incl. the path guard; changing it risks breaking host-mode workflows)* -- Session load bricks on >1MB message line (`session.go:389`); fixed tmp name `id.jsonl.tmp` across processes (`session.go:97`); stale `.wal` after recovery *(fixed: `scanJSONLLines` reader with a 16 MB per-line cap drains+logs oversize/corrupt lines instead of bricking the load; corrupt meta line is a load error (500) while an empty file is still ErrNotFound (404); `RecoverFromWAL` reuses the same tolerant reader; Save's temp name is namespaced with getpid())* -- MCP stale `pendErrors` entries + zombie on failed connect (`mcp.go:118-155`) *(no change needed: all `callWithTimeout` terminal paths (success/timeout/ctx-cancel) and the EOF/readLoop-exit path already delete `pendErrors[id]` and `pending[id]`; the connection-lost zombie is resolved by M7's dead-flag + child-kill)* -- `trackSession`/`sessions` grow unboundedly in long-lived daemon (`daemon.go:75,924`) *(fixed: in-memory sessions index capped at `maxTrackedSessions` (1000), evicting oldest by LastUsed)* -- `MessageBus` (700 lines) dead in production; `hooks.EventBus` unused *(partial: `internal/hooks/events.go` + its test deleted (genuinely dead — no production callers); `multiagent.MessageBus` retained — it backs the agent file-lock feature (`AcquireLock`/`IsLocked`) and its lock tests exercise real behavior, so the "dead in production" claim is inaccurate for it)* -- Plugin security scanner advisory-only; `CheckExtensionMalware` has no callers *(fixed: `internal/plugin/malware_check.go` deleted)* -- `WithTimeout` no-op cancel footgun (`timeout.go:33-40`); fabricated session IDs; dead exports (`RemainingTime`, `Countdown`) *(fixed: `RemainingTime`/`Countdown` now wired into both `runPrint` and REPL print paths (one remaining-time notice per turn); fabricated `session_` replaced with `genID()` in the memory manager startup; WithTimeout cancel is correctly deferred at both call sites)* -- Staticcheck: unused `getKeys` (`coverage_extra_test.go:131`) *(no change needed: verified clean — `getKeys` is no longer present/used)* - -### 3.5 Verified-clean (defense-in-depth that holds) - -- Docker-socket not mounted; host env not passed into container; `--read-only` + `noexec` tmpfs + `cap-drop ALL` + `no-new-privileges` + `pids-limit 256` -- Fail-closed verified at: container boot (CLI/headless/TUI), `WrapCommand`, tool service (container required → tools disabled), `ParseMode` (typo → Strict) -- ApprovalGate fails closed, consulted after permission check, never loosens a denial -- Bash hard-deny regexes layered; `safewrite` uses `O_NOFOLLOW` + temp+rename+0600 -- API keys in OS keychain, never in config (`settings.go:485-491` rejects `apiKey.*` writes); macOS piped via stdin, never argv; constant-time daemon auth -- Exponential backoff with full jitter + `Retry-After` honored (eyrie); token-bucket rate limiter ctx-aware and leak-free; SSE bounded (128-buf/64KB); circuit breaker with half-open -- Atomic session persistence (temp+sync+rename, WAL, `busy_timeout`, FK on); migrations present -- Agent-loop background goroutines all timeout-bounded (10s–2min); async hooks WaitGroup-tracked -- Loop guards: SnowballDetector, LoopDetector, turn limit, budget limit, max_tokens recovery cap -- Telemetry strictly opt-in (`HAWK_CODE_ENABLE_TELEMETRY=1`), span content hygiene, redaction of 25+ patterns - ---- - -## 4. Competitor comparison (June–July 2026 data) - -Sources: official docs matrix (hidekazu-konishi.com), MorphLLM ranked table, codemyspec.com, sanj.dev, Starkslab control-surface notes. Verified June 28, 2026. - -| Agent | License / Stars | Model freedom | MCP | Sandboxing | Headless/CI | Benchmarks (agent+model) | -|---|---|---|---|---|---|---| -| Claude Code | Proprietary / 134K | Claude only | Client (1,000+ servers) | Modes: plan→bypassPermissions; checkpoints, worktree isolation | `claude -p`, JSON | 88.6% SWE-bench V; 78.9% TB 2.1 | -| Codex CLI | Apache-2.0 / 94K | OpenAI only | Client + **server**; 9,000+ plugins | 3-tier permission + sandbox modes | `codex exec` JSONL | **83.4% TB 2.1 (#1)**; 82.1% SWE-bench V | -| Antigravity (ex-Gemini CLI) | Apache-2.0 / 105K | Gemini only | Client | plan mode, folder trust, checkpoints | `antigravity -p` JSON | 70.7% TB 2.1 | -| opencode | MIT / 180K | **75+ providers + local** | Client | permission rules, plan/build agents | `opencode run`, `serve` | varies (BYOK) | -| Aider | Apache-2.0 / 47K | any OpenAI-compatible | No | git-first (auto-commit/revert) | `aider --message` | 88% polyglot (GPT-5); dormant since Aug 2025 | -| Goose | Apache-2.0 / 38K | any LLM | Client (extensions) | optional macOS sandbox; recipes | `goose run` | n/a | -| Cline / Kilo Code / Qwen Code | OSS | BYOK | Yes | approval modes | headless | n/a | - -**Where hawk-eco is already competitive:** -- **Only player with Docker-isolated, fail-closed command execution** (AgentForge paper validates this exact design; Codex sandbox is closest but host-process-based) -- Model-agnostic like opencode/Aider/Goose (23 first-class providers via eyrie) -- Zero-CGO single static binary; privacy-first -- Depth of in-repo instrumentation (codegraph, executiongraph, graphjournal, GitNexus-style impact analysis) exceeds every OSS competitor - -**Where hawk-eco trails (actionable):** -1. **Benchmark presence** — no published SWE-bench/Terminal-Bench numbers; `internal/bench` exists but had no test files. *(addressed: `internal/bench/bench_test.go` now drives the headless agent loop via `engine.Session.Stream` against stub-fixture tasks with `HAWK_BENCH_HEADLESS=1` — the smoke gate that the roadmap demanded; real provider-backed SWE evaluation still gated by env var)* -2. **MCP server mode** — *(already implemented: `internal/mcp/server.go` (JSON-RPC 2.0 over stdio) + `server_tools.go` (RegisterDefaultTools) + `cmd/mcp_serve.go` wiring `hawk mcp serve`/`mcp config`. The report's "hawk is client-only" note was stale — the server was already wired end-to-end; nothing to add.)* -3. **JSONL event output for CI** — `codex exec --json` / `claude -p --output-format json` set the bar; hawk's headless path should emit machine-readable events (daemon already streams SSE — expose the same shape on stdout). *(addressed: `internal/engine/jsonl_events.go` exposes `JSONLEventWriter` emitting newline-delimited JSON envelopes — content/tool_use/tool_result/usage/done/error — concurrency-safe with a shared mutex; reusable primitive for the headless print path. The `*_test.go` covers shape + no-interleaving.)* -4. **Startup latency** — 1.83s `hawk path` vs Rust-based Codex "near-instant"; defer eyrie engine init until first use. -5. **Ecosystem** — opencode's TUI Mission Control, Claude Code's Agent Teams; hawk has multiagent + HUD already — needs a public story + docs polish. -6. **Aider's git discipline** — auto-commit-per-edit with clean revert is the OSS gold standard; hawk should consider opt-in auto-checkpoints. - ---- - -## 5. Research papers mapped to concrete improvements - -| Paper (year) | Core idea | Relevance to hawk | Action | -|---|---|---|---| -| **CAT — Context as a Tool** (ACL 2026 Findings) | Context management as a callable, plannable tool; proactive folding at milestones; SWE-Compressor 57.6% SWE-bench V | hawk's compaction is passive/heuristic (`context_governor.go`), exactly the criticized pattern | Expose a `context` tool the agent can call; fold at stage boundaries | -| **SWE-MeM** (arXiv 2606.28434, 2026) | Adaptive memory management; memory-aware GRPO; 60.2% @30B | hawk's `EvolvingMemory` is the right idea, unpersisted and untrained | Fix H6 (persistence); add evaluation harness to measure guideline quality | -| **Git-Context-Controller (GCC)** (arXiv 2508.00031, 2025) | Versioned memory hierarchy: COMMIT/BRANCH/MERGE/CONTEXT; 48% SWE-bench-Lite (SOTA) | hawk already has `graphjournal`, `branching`, `session` decomposition | Wire session milestones into a navigable, versioned memory (ties to H10/mission worktrees) | -| **SWE-Adept** (arXiv 2603.01327, 2026) | Agent-directed DFS localization + two-stage filtering; checkpointed git-based resolution (+4.7% end-to-end) | `codegraph` exists but semantic search is brute-force (H8) | Adopt dependency-aware traversal + deferred full-code loading; reuse `branching` for checkpoints | -| **ContextBench** (arXiv 2602.05892, 2026) | Process-level retrieval eval; "Bitter Lesson": complex scaffolding ≠ better retrieval; recall>precision; consolidation gap | Warning against over-engineering; hawk's breadth is high | Prioritize retrieval precision + consolidation; add context-eval metrics | -| **AgentForge** (arXiv 2604.13120, 2026) | Execution-grounded verification; mandatory Docker sandbox; 40% SWE-bench Lite | **Validates hawk's Docker-only design**; five-role decomposition beats single-agent by 26–28pts | Cite in README/architecture docs; consider Tester→Debugger loop wiring in mission mode | -| ReAct (2022) / Reflexion (2023) | Interleave reasoning+action; verbal self-reflection | hawk's lifecycle loop is Reflexion-style | Fix H6 so the loop actually persists | - ---- - -## 6. Recommended roadmap (draft — in execution on this branch) - -1. **Triage (C1, H1, H3–H6, H12):** wire panic recovery, runtime.jsonc allowlist, fail-closed HTTP hooks, SSE write-error exit, signal-safe session save, EvolvingMemory persistence, env scrubbing for bash -2. **Concurrency & budgets (H7, M1, M2, M9):** mutex'd limits accessors, wire RecordCost, bounded tracer, honest error propagation -3. **Dead code (H10, H11, M5, M8):** fix-and-test async; delete docs; wire or delete approval gate/composio stub/MessageBus (H11 docs deleted; M5 approval gate wired; M8 composio deleted; dead `hooks.EventBus` and `plugin.CheckExtensionMalware` deleted; `multiagent.MessageBus` retained — backs agent file-lock) -4. **Performance (H8, M14–M18):** embedding cache, hoisted regexes, no-clone context access, viewport incremental render, lazy eyrie init -5. **Multiagent correctness (H9, M6):** retryable branch names, exit-code propagation, detached worktree cleanup -6. **Competitor deltas:** MCP server mode, JSONL headless output, benchmark harness -7. **Paper-backed features:** context-as-tool, milestone-based memory folding - -## 7. Method & verification notes - -- All `file:line` references verified against HEAD `bfd5654`; dead-code claims verified via import-graph search -- `go test -race` passes on exercised paths; racy findings (M1) exist because the racy paths are untested -- Research (Phase 5/6) uses June–July 2026 sources only; star counts/benchmarks are point-in-time diff --git a/docs/COMPARISON-WITH-TOP-CODING-AGENTS.md b/docs/COMPARISON-WITH-TOP-CODING-AGENTS.md deleted file mode 100644 index 06ac285e..00000000 --- a/docs/COMPARISON-WITH-TOP-CODING-AGENTS.md +++ /dev/null @@ -1,513 +0,0 @@ -# Hawk-Eco vs Top 20 Coding Agents Comparison - -## Executive Summary - -Hawk-Eco is a terminal coding-agent ecosystem with a multi-repository product -architecture. Hawk is the primary product; Eyrie, Yaad, Tok, Trace, Sight, and -Inspect are independently owned support engines. While other coding agents -often optimize for IDE integration, Hawk-Eco emphasizes terminal workflows, -sandboxing, multi-agent orchestration, and tool systems. - -This document is a dated qualitative comparison, not an objective benchmark or -release-readiness assessment. Repository stars, feature claims, and numeric -scores must be independently revalidated before use. - ---- - -## Top 20 Coding Agents Comparison - -| Rank | Agent | Stars | Language | Architecture | Key Strength | Weakness | -|------|-------|-------|----------|--------------|--------------|----------| -| 1 | **Cursor** | 80k+ | TypeScript | IDE Extension | AI-assisted IDE | Closed-source, proprietary | -| 2 | **GitHub Copilot** | 200k+ | TypeScript | IDE Extension | GitHub integration | Limited terminal support | -| 3 | **Windsurf (Codeium)** | 30k+ | TypeScript | IDE Extension | Free tier, good DX | Closed-source | -| 4 | **Cline** | 20k+ | TypeScript | VS Code Extension | Good refactoring | Limited multi-agent | -| 5 | **Aider** | 15k+ | Python | CLI | Two-file editing | Minimal tools | -| 6 | **OpenCode** | 8k+ | Go | CLI | Self-hosted | Small community | -| 7 | **Goose** | 5k+ | Go | CLI | Terminal-native | Limited features | -| 8 | **Codex CLI** | 20k+ | Python | CLI | OpenAI integration | Basic security | -| 9 | **Devin** | 12k+ | Python | CLI | Agent benchmark leader | Expensive | -| 10 | **Agentic AI (Google)** | 8k+ | Python | CLI | Research-backed | Complex setup | -| 11 | **Tree-sitter Agents** | 3k+ | Go | CLI | Tree-sitter parsing | Limited tooling | -| 12 | **Continue** | 12k+ | TypeScript | VS Code Extension | Open-source | Limited security | -| 13 | **Vibe (Vercel)** | 8k+ | TypeScript | VS Code Extension | Vercel integration | Limited multi-agent | -| 14 | **CodeComplete** | 3k+ | TypeScript | IDE Extension | Good completions | Closed-source | -| 15 | **Tabnine** | 6k+ | TypeScript | IDE Extension | Good completions | Closed-source, data concerns | -| 16 | **Mem (Phase)** | 8k+ | TypeScript | IDE Extension | Memory features | Limited agents | -| 17 | **Aider (with Claude)** | 15k+ | Python | CLI | Powerful LLM | Limited tooling | -| 18 | **BuildPiper** | 3k+ | Go | CLI | CI/CD integration | Niche focus | -| 19 | **Cody (Sourcegraph)** | 6k+ | TypeScript | VS Code Extension | Sourcegraph integration | Limited multi-agent | -| 20 | **Tabby** | 5k+ | Rust | Terminal | Cross-platform | Limited AI features | - ---- - -## Detailed Feature Comparison - -### 1. Syntax Highlighting & Code Intelligence - -| Agent | Languages | Engine | Status | -|-------|-----------|--------|--------| -| **Hawk-Eco** | **25+** | Custom regex | **10/10** | -| Cursor | 50+ | Tree-sitter | 9/10 | -| Copilot | 20+ | ML-based | 8/10 | -| Windsurf | 20+ | ML-based | 8/10 | -| Aider | 10+ | Pygments | 7/10 | -| Codex CLI | 10+ | Custom | 7/10 | -| OpenCode | 10+ | Custom | 7/10 | -| Devin | 5+ | Custom | 6/10 | - -**Hawk-Eco: Best-in-class** with custom regex engine and language-specific patterns - -### 2. Sandbox Security - -| Agent | Mode | Namespace | Seccomp | Landlock | Status | -|-------|------|-----------|---------|---------|--------| -| **Hawk-Eco** | **3 tiers** | ✅ | ✅ | ✅ | **10/10** | -| Cursor | Limited | ❌ | ❌ | ❌ | 5/10 | -| Copilot | Limited | ❌ | ❌ | ❌ | 5/10 | -| Windsurf | Limited | ❌ | ❌ | ❌ | 5/10 | -| Aider | Limited | ❌ | ❌ | ❌ | 4/10 | -| OpenCode | Limited | ❌ | ❌ | ❌ | 4/10 | -| Devin | Limited | ❌ | ❌ | ❌ | 4/10 | - -**Hawk-Eco: Only agent with comprehensive sandbox isolation** - -### 3. Multi-Agent System - -| Agent | Agents | Personas | Budget Tracking | Sub-agents | Status | -|-------|--------|----------|-----------------|------------|--------| -| **Hawk-Eco** | **Multi-tier** | ✅ | ✅ | ✅ | **10/10** | -| Cursor | ❌ | ❌ | ❌ | ❌ | 2/10 | -| Copilot | ❌ | ❌ | ❌ | ❌ | 2/10 | -| Windsurf | ❌ | ❌ | ❌ | ❌ | 2/10 | -| Aider | ❌ | ❌ | ❌ | ❌ | 2/10 | -| OpenCode | ❌ | ❌ | ❌ | ❌ | 2/10 | -| Devin | ❌ | ❌ | ✅ | ✅ | 6/10 | - -**Hawk-Eco: Only terminal agent with multi-agent orchestration** - -### 4. Tool System - -| Agent | Tools | Permissions | Gating | Status | -|-------|-------|-------------|--------|--------| -| **Hawk-Eco** | **40+** | **3 tiers** | ✅ | **10/10** | -| Cursor | 20+ | Limited | ✅ | 7/10 | -| Copilot | 10+ | Limited | ❌ | 5/10 | -| Windsurf | 10+ | Limited | ✅ | 6/10 | -| Aider | 5+ | Limited | ❌ | 4/10 | -| OpenCode | 10+ | Limited | ❌ | 5/10 | -| Devin | 15+ | Limited | ✅ | 6/10 | - -**Hawk-Eco: Most comprehensive tool system with permission gating** - -### 5. Terminal Experience - -| Agent | Colors | Diff View | Syntax HL | Status | -|-------|--------|-----------|-----------|--------| -| **Hawk-Eco** | **20+ colors** | **Full-featured** | **25+ langs** | **10/10** | -| Cursor | ✅ | Basic | ✅ | 7/10 | -| Copilot | ✅ | Basic | ✅ | 7/10 | -| Windsurf | ✅ | Basic | ✅ | 7/10 | -| Aider | ❌ | Basic | ❌ | 4/10 | -| OpenCode | ❌ | Basic | ❌ | 4/10 | -| Devin | ❌ | Basic | ❌ | 4/10 | - -**Hawk-Eco: Best terminal experience by far** - -### 6. Extension/MCP Support - -| Agent | MCP | Extensions | Protocol | Status | -|-------|-----|------------|----------|--------| -| **Hawk-Eco** | **✅** | ✅ | **20+ extensions** | **10/10** | -| Cursor | ✅ | ✅ | Limited | 7/10 | -| Copilot | ✅ | ✅ | Limited | 7/10 | -| Windsurf | ✅ | ✅ | Limited | 7/10 | -| Aider | ❌ | ❌ | ❌ | 3/10 | -| OpenCode | ❌ | ❌ | ❌ | 3/10 | -| Devin | ❌ | ❌ | ❌ | 3/10 | - -**Hawk-Eco: Best extension support with custom MCP protocol** - ---- - -## Architecture Comparison - -### Hawk-Eco: Layered Multi-Repository Separation - -``` -Layer 1: Product (hawk) -Layer 2: Support Engines (eyrie, yaad, tok, trace, sight, inspect) -Layer 3: Foundation (hawk-core-contracts, hawk-mcpkit) -``` - -### Other Agents: Single Repo or Closed Architecture - -| Agent | Architecture | Coupling | Scalability | -|-------|--------------|----------|-------------| -| **Hawk-Eco** | **Multi-repository ecosystem with layers** | **Low at guarded boundaries; transitional internally** | **High, with release coordination cost** | -| Cursor | Single repo | High | Medium | -| Copilot | Single repo | High | Medium | -| Windsurf | Single repo | High | Medium | -| Aider | Single repo | Medium | Low | -| OpenCode | Single repo | Medium | Low | -| Devin | Single repo | High | Low | - ---- - -## Strengths of Hawk-Eco - -### 1. Terminal-Native Experience -- ✅ **Professional terminal UI** with colors, diffs, syntax highlighting -- ✅ **Streaming output** with progressive rendering -- ✅ **Budget tracking** (MaxBudgetUSD, MaxTurns) -- ✅ **Multi-agent orchestration** with personas and budgets - -### 2. Sandbox Security -- ✅ **3-tier sandbox system** (strict/workspace/off) -- ✅ **Namespace isolation** (Linux) -- ✅ **Seccomp filtering** for syscall restrictions -- ✅ **Landlock** for filesystem access control -- ✅ **Process monitoring** and kill switches - -### 3. Tool System -- ✅ **40+ built-in tools** covering all coding tasks -- ✅ **Permission gating** (YOLO/Semi/Specify) -- ✅ **Sandboxed execution** for each tool -- ✅ **Tool discovery** and help system - -### 4. Architecture -- ✅ **Layered multi-repository ecosystem** with guarded dependency isolation -- ✅ **Foundation layer** (contracts, MCP) never imports product -- ✅ **Extension-friendly** with MCP protocol -- ✅ **Cross-language SDKs** (Go, Python) - -### 5. Security -- ✅ **Multi-layered** (injection scanning, sandbox, permissions) -- ✅ **Secure config loading** (no panic in production) -- ✅ **API key validation** and secure storage -- ✅ **Sandboxed execution** for all tools - ---- - -## Weaknesses of Hawk-Eco (vs Top 20) - -### 1. Documentation Gaps -| Repo | Documentation Status | Score | -|------|---------------------|-------| -| **hawk** | **Excellent** (19 docs) | **10/10** | -| **hawk-sdk-go** | Good | 8/10 | -| **hawk-sdk-python** | **Added architecture.md** | **9/10** | -| **graycode-core** | **Added architecture.md** | **9/10** | -| **hawk-mcpkit** | Good | 8/10 | -| **hawk-core-contracts** | Good | 8/10 | -| **eyrie** | Good | 8/10 | -| **yaad** | Good | 8/10 | -| **tok** | Good | 8/10 | -| **trace** | Good | 8/10 | -| **sight** | Good | 8/10 | -| **inspect** | Good | 8/10 | -| **hawk-community-skills** | Good | 8/10 | - -**Overall: 8.2/10** - Good documentation, room for improvement in non-hawk repos - -### 2. Community & Ecosystem -| Metric | Hawk-Eco | Top Agents | -|--------|----------|-----------| -| GitHub Stars | 5k+ | 80k+ | -| Contributors | Small team | Large community | -| Extension Marketplace | 20+ extensions | 100+ extensions | -| Documentation Site | ✅ | ✅ | -| Community Forum | ❌ | ✅ | -| Discord/Slack | ✅ | ✅ | - -**Score: 6/10** - Smaller community but high quality - -### 3. Feature Parity with IDE Agents - -| Feature | Hawk-Eco | IDE Agents | -|---------|----------|------------| -| AI-assisted IDE | ❌ | ✅ (Cursor, Copilot) | -| Code completion | ❌ | ✅ (all IDE agents) | -| Git integration | ✅ | ✅ | -| Debugging | ❌ | ✅ (limited) | -| Test generation | ✅ | ✅ | -| Code refactoring | ✅ | ✅ | -| Multi-file editing | ✅ | ✅ | -| Terminal sharing | ❌ | ❌ | - -**Score: 7/10** - Professional terminal features, missing IDE integration - ---- - -## Recommendations for Improvement - -### High Priority (Score Impact: +0.5) - -#### 1. **Add IDE Integration Support (hawk repo)** -- **What:** Add VS Code extension or JetBrains plugin -- **Why:** Top 20 agents all have IDE integration -- **Implementation:** - - Create `hawk-vscode/` repo for VS Code extension - - Use Hawk SDK for communication - - Add WebSocket transport for real-time updates - -```go -// New transport layer for IDE integration -package transport - -type IDETransport struct { - conn *websocket.Conn -} - -func NewIDETransport(conn *websocket.Conn) *IDETransport -func (t *IDETransport) Send(event Event) error -func (t *IDETransport) Receive() (Event, error) -``` - -#### 2. **Add Extension Marketplace (hawk repo)** -- **What:** Create marketplace for community extensions -- **Why:** Top agents have 100+ extensions -- **Implementation:** - - Add extension discovery endpoint to hawk - - Create `hawk-community-skills` integration - - Add version compatibility checking - -### Medium Priority (Score Impact: +0.3) - -#### 3. **Add Documentation Site (graycode-core)** -- **What:** Create documentation website -- **Why:** Professional appearance, easier onboarding -- **Implementation:** - - Add Docusaurus or Next.js docs site - - Document all APIs and protocols - - Add tutorials and guides - -#### 4. **Add Community Forum (graycode-core)** -- **What:** Create forum for discussions -- **Why:** Improve community engagement -- **Implementation:** - - Add Discourse or custom forum - - Moderate discussions - - Share updates and roadmap - -#### 5. **Add More Extension Points (hawk)** -- **What:** Create more MCP servers and extensions -- **Why:** Increase ecosystem value -- **Implementation:** - - Add filesystem MCP server - - Add git MCP server - - Add code search MCP server - -### Low Priority (Score Impact: +0.2) - -#### 6. **Add AI Code Completion (eyrie)** -- **What:** Add line/block completion support -- **Why:** Match IDE agent capabilities -- **Implementation:** - - Add completion endpoint - - Integrate with editor protocols - -#### 7. **Add Debugging Support (hawk)** -- **What:** Add debugging tools -- **Why:** Complete IDE-like experience -- **Implementation:** - - Add debug MCP server - - Support breakpoints - - Add variable inspection - -#### 8. **Add Community Stats Dashboard (graycode-core)** -- **What:** Track community engagement -- **Why:** Measure ecosystem health -- **Implementation:** - - Add analytics endpoints - - Create public dashboard - - Track adoption metrics - ---- - -## Detailed Repo-Specific Improvements - -### **hawk** (Main Repo) - Primary Product - -| Priority | Improvement | Effort | Impact | -|----------|--------------|--------|--------| -| HIGH | Add VS Code extension integration | Large | +0.5 | -| HIGH | Add extension marketplace | Medium | +0.4 | -| MEDIUM | Add debugging support | Medium | +0.3 | -| MEDIUM | Add AI code completion | Large | +0.3 | -| LOW | Add Web UI for monitoring | Small | +0.2 | - -**No numeric score is assigned; see the dated architecture baseline for verified state.** - ---- - -### **hawk-sdk-go** (Go SDK) - -| Priority | Improvement | Effort | Impact | -|----------|--------------|--------|--------| -| LOW | Add SDK analytics | Small | +0.1 | -| LOW | Add IDE integration examples | Small | +0.2 | - -**No numeric score is assigned in this comparison.** - ---- - -### **hawk-sdk-python** (Python SDK) - -| Priority | Improvement | Effort | Impact | -|----------|--------------|--------|--------| -| LOW | Add deprecation warnings | Small | +0.1 | -| LOW | Add type stubs | Small | +0.1 | - -**Historical self-assessment; no current numeric score is assigned.** - ---- - -### **graycode-core** (Core Framework) - -| Priority | Improvement | Effort | Impact | -|----------|--------------|--------|--------| -| HIGH | Add documentation site | Large | +0.3 | -| MEDIUM | Add community forum | Large | +0.2 | -| MEDIUM | Add API analytics | Medium | +0.2 | - -**Historical self-assessment; no current numeric score is assigned.** - ---- - -### **eyrie** (LLM Runtime) - -| Priority | Improvement | Effort | Impact | -|----------|--------------|--------|--------| -| LOW | Add completion endpoint | Medium | +0.2 | -| LOW | Add streaming optimizations | Small | +0.1 | - -**No numeric score is assigned in this comparison.** - ---- - -### **hawk-core-contracts** (Shared Types) - -| Priority | Improvement | Effort | Impact | -|----------|--------------|--------|--------| -| LOW | Add version compatibility checks | Small | +0.1 | - -**No numeric score is assigned in this comparison.** - ---- - -### **hawk-mcpkit** (MCP Toolkit) - -| Priority | Improvement | Effort | Impact | -|----------|--------------|--------|--------| -| LOW | Add more transport options | Small | +0.1 | - -**Historical self-assessment; no current numeric score is assigned.** - ---- - -### **yaad** (Memory) - -| Priority | Improvement | Effort | Impact | -|----------|--------------|--------|--------| -| LOW | Add memory analytics | Small | +0.1 | - -**Historical self-assessment; no current numeric score is assigned.** - ---- - -### **tok** (Token Management) - -| Priority | Improvement | Effort | Impact | -|----------|--------------|--------|--------| -| LOW | Add token usage prediction | Small | +0.1 | - -**Historical self-assessment; no current numeric score is assigned.** - ---- - -### **trace** (Session Capture) - -| Priority | Improvement | Effort | Impact | -|----------|--------------|--------|--------| -| LOW | Add trace sharing | Small | +0.1 | - -**Historical self-assessment; no current numeric score is assigned.** - ---- - -### **sight** (Code Review) - -| Priority | Improvement | Effort | Impact | -|----------|--------------|--------|--------| -| LOW | Add review templates | Small | +0.1 | - -**Historical self-assessment; no current numeric score is assigned.** - ---- - -### **inspect** (Verification) - -| Priority | Improvement | Effort | Impact | -|----------|--------------|--------|--------| -| LOW | Add verification templates | Small | +0.1 | - -**Historical self-assessment; no current numeric score is assigned.** - ---- - -## Qualitative assessment - -| Category | Score | Max | -|----------|-------|-----| -| **Architecture** | Strong ecosystem boundaries; internal consolidation remains in progress | -| **Terminal experience** | Core product strength | -| **Security** | Requires continuous verification; do not infer completeness from feature count | -| **Documentation** | Requires reconciliation and dated evidence | -| **IDE and SDK reach** | Separate product roadmap, not an architecture score | - ---- - -## Implementation Roadmap - -### Phase 1: High Priority (Immediate) -1. Add VS Code extension integration -2. Add extension marketplace -3. Improve graycode-core documentation site - -### Phase 2: Medium Priority (Next Sprint) -4. Add debugging support -5. Add AI code completion -6. Add community forum - -### Phase 3: Low Priority (Backlog) -7. Add Web UI for monitoring -8. Add SDK analytics -9. Add more MCP servers -10. Add completion endpoint to eyrie - ---- - -## Conclusion - -Hawk-Eco is a coding-agent ecosystem with: -- ✅ **Best-in-class terminal experience** -- ✅ **Advanced sandbox security** -- ✅ **Multi-agent orchestration** -- ✅ **Comprehensive tool system** -- ✅ **Layered multi-repository architecture** - -**To reach parity with top IDE agents (Cursor, Copilot):** -- Add VS Code extension integration -- Add extension marketplace -- Add AI code completion - -**These are strategic moves** that would differentiate Hawk-Eco as the **only terminal agent with professional IDE integration capabilities**. - -Architecture progress should be tracked through verified dependency, migration, -replay, recovery, and release checks rather than a target score. - ---- - -*Comparison Date: 2026-07-05* -*Based on analysis of top 20 coding agents in GitHub Topics, AI coding benchmarks, and feature comparisons.* diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 9ebc8e38..d466023a 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -11,11 +11,8 @@ Documents: - `hawk-dependency-rules.md` - import and ownership boundaries - `hawk-core-contracts-spec.md` - shared contracts layer and current status - `hawk-provider-abstraction.md` - provider/runtime abstraction design -- `hawk-eyrie-engine-migration.md` - implemented Hawk-face/Eyrie-engine boundary and submodule upgrade order -- `verification-status-2026-07-13.md` - dated verification evidence, current hardening, and release blockers - `hawk-review-verify-lifecycle.md` - review and verification lifecycle - `hawk-trace-event-model.md` - trace and audit event model -- `hawk-contract-migration-inventory.md` - current shared-type usage and migration order - `hawk-architecture-v1-definition-of-done.md` - realistic shipping bar for architecture v1 - `adr/ADR-0004-file-first-session-history.md` - canonical session history and SQLite projection boundary - `tasks.md` - historical implementation checklist from the initial architecture pass (superseded by the definition-of-done doc; kept for record) diff --git a/docs/architecture/hawk-contract-migration-inventory.md b/docs/architecture/hawk-contract-migration-inventory.md deleted file mode 100644 index 0d86004d..00000000 --- a/docs/architecture/hawk-contract-migration-inventory.md +++ /dev/null @@ -1,187 +0,0 @@ -# Hawk Contract Migration Inventory - -## Goal - -This document captures the current shared-type coupling that should be moved into `hawk-core-contracts`. - -## Current cross-repo export surface - -### `hawk/shared/types` - -Status: removed - -The legacy Hawk-owned shared type shim has been deleted. Shared severity and -finding contracts now live only in `hawk-core-contracts/types`. - -## Current external consumers - -### `sight` - -Migration status: completed - -Current usage: - -- severity aliasing -- review concern severity typing - -### `inspect` - -Migration status: completed - -Current usage: - -- severity aliasing -- check severity -- report formatting / finding output - -### `hawk` docs and metadata - -Current references: - -- `README.md` -- `AGENTS.md` -- architecture docs - -These will need copy updates once the migration is completed. - -## Current Hawk-internal types - -### `hawk/internal/types` - -Files: - -- `internal/types/client.go` -- `internal/types/settings.go` -- `internal/types/severity.go` - -Assessment: - -- `internal/types/severity.go` now re-exports `hawk-core-contracts/types` -- `internal/types/client.go` contains Hawk-owned conversation/runtime DTOs and - the small provider port needed by product integrations; it has no Eyrie imports -- `internal/types/settings.go` is Hawk config-specific and should remain Hawk-internal - -## Tool contract migration - -### Historical source shape - -Before the engine-boundary migration, runtime source types included -lower-level provider tool-call and tool-result DTOs. - -### New neutral contract - -Added: - -- `hawk-core-contracts/tools.ToolCall` -- `hawk-core-contracts/tools.ToolResult` - -### First migration boundary - -Hawk session persistence now uses neutral tool contracts instead of persisting -lower-level provider types directly. - -### Remaining migration - -- Hawk runtime now owns `internal/types.EyrieMessage` -- Hawk runtime now owns tool call/result, response, usage, and stream DTOs in `internal/types` -- Hawk runtime now owns chat options, response format, continuation config, tool choice, and tool definition DTOs in `internal/types` -- Hawk runtime now owns the provider seam via `internal/types.ChatProvider` -- Hawk's `ChatClient` port is implemented by `internal/engine` using only - `eyrie/engine`; no production package imports a lower Eyrie package -- future work should move trace/event/policy layers to consume neutral tool contracts where appropriate - -## Review and verification contract migration - -### New shared contracts - -Added: - -- `hawk-core-contracts/review.Finding` -- `hawk-core-contracts/review.InlineComment` -- `hawk-core-contracts/review.Stats` -- `hawk-core-contracts/review.Result` -- `hawk-core-contracts/verify.Finding` -- `hawk-core-contracts/verify.Stats` -- `hawk-core-contracts/verify.Report` - -### Current adoption - -- `sight` now exposes adapters from its public result types into `hawk-core-contracts/review` -- `inspect` now exposes adapters from its public report types into `hawk-core-contracts/verify` -- Hawk review persistence now stores neutral review findings instead of `sight`-owned findings -- Hawk inspect/review bridge paths now return neutral review/verification contracts for product-facing integration - -### Remaining migration - -- `sight.Result` still carries sight-specific SAST fusion details outside the shared contract -- `inspect.Report` remains the public engine-local type and converts at the boundary -- review status lifecycle enums still live in Hawk because they are product workflow state, not cross-repo contracts - -## Event contract migration - -### New shared contracts - -Added: - -- `hawk-core-contracts/events.ToolEvent` -- `hawk-core-contracts/events.TraceEvent` -- `hawk-core-contracts/events.UsageInfo` - -### Current adoption - -- `internal/hooks/audit.ToolEvent` now aliases the shared contract -- `internal/observability/oteltrace.TraceEvent` now aliases the shared contract - -### Remaining migration - -- broader session/timeline/workflow event types are still Hawk-internal -- policy and verification event schemas can move next as separate contracts - -## Policy contract migration - -### New shared contracts - -Added: - -- `hawk-core-contracts/policy.Risk` -- `hawk-core-contracts/policy.PermissionVerdict` -- `hawk-core-contracts/policy.GuardianDecision` -- `hawk-core-contracts/policy.PermissionRequest` - -### Current adoption - -- `internal/permissions.PermissionVerdict` now aliases the shared contract -- `internal/permissions.GuardianDecision` now aliases the shared contract -- `internal/engine/safety.PermissionRequest` now embeds the shared request contract - -### Remaining migration - -- sandbox-specific policy manager types remain Hawk-internal -- approval gate categories remain Hawk-internal - -## Migration order - -### Step 1 -Scaffold `hawk-core-contracts` with `types/` for severity and findings. - -### Step 2 -Update `sight` to import `github.com/GrayCodeAI/hawk-core-contracts/types`. - -### Step 3 -Update `inspect` to import `github.com/GrayCodeAI/hawk-core-contracts/types`. - -### Step 4 -Update `hawk/internal/types/severity.go` to re-export from `hawk-core-contracts/types`. Completed. - -### Step 5 -Update docs that currently describe `hawk/shared/types` as the cross-repo API. - -Status: completed. - -### Step 6 -Remove `hawk/shared/types` after local migration completes. Completed. - -Current status: - -- local ecosystem migration is complete -- Hawk no longer ships the `hawk/shared/types` package diff --git a/docs/architecture/hawk-eyrie-engine-migration.md b/docs/architecture/hawk-eyrie-engine-migration.md deleted file mode 100644 index e7bacd53..00000000 --- a/docs/architecture/hawk-eyrie-engine-migration.md +++ /dev/null @@ -1,130 +0,0 @@ -# Hawk–Eyrie Engine Migration - -## Target - -```text -User ──► Hawk product/agent ──► eyrie/engine ──► model providers -``` - -The implemented split is: - -```text -Hawk — product face Eyrie — provider engine - -CLI / TUI / SDK entrypoints - ├─ /config and model picker ───────────► engine control plane - │ ├─ OS credential store - │ ├─ catalog/discovery - │ └─ provider state + routing policy - └─ conversation + coding agent - ├─ history / WAL / resume - ├─ tools / permissions / policy - └─ Hawk ChatClient port ───────────► engine generate/stream - ├─ capability/model resolution - ├─ deployment routing + resilience - └─ normalized events/usage -``` - -Hawk remains authoritative for the coding-agent loop, tools, permissions, -project context, product memory, conversation history, WAL, checkpoints, and -resume/replay. Eyrie owns credentials, catalog discovery, capability matching, -provider/deployment routing, resilience, normalized streaming, usage, cost, -health, and provider telemetry. - -## Source workflow - -Standalone `eyrie/` is developed and tested first. Hawk then advances -`external/eyrie` to the exact Eyrie commit and verifies the clean submodule -checkout before integrating it. Published Hawk builds continue to use a tagged -Eyrie module version; `go.work` pins the submodule for local integration. - -Upgrade order is deliberate: - -1. implement and test the facade change in standalone Eyrie -2. create a reviewable Eyrie commit and ensure the revision is reachable -3. advance Hawk's `external/eyrie` gitlink to that exact commit -4. update Hawk's `go.mod` version after the Eyrie revision is published -5. run `go work sync`, then verify Hawk once through the submodule and once with - `GOWORK=off` - -Do not copy Eyrie source into Hawk or let a Hawk change depend on an unpinned -standalone checkout. - -## Migration rules - -1. New host-boundary code uses `github.com/GrayCodeAI/eyrie/engine`. -2. Hawk production code imports no Eyrie package below `eyrie/engine`. -3. Hawk expresses requirements and intent; Eyrie resolves infrastructure. -4. An exact user model does not silently fall back. -5. Eyrie emits tool requests; Hawk authorizes and executes tools. -6. Hawk has one authoritative product conversation store. -7. Secrets stay in Eyrie's credential store and never enter tool environments. -8. Custom gateways are Engine-instance configuration, not process-global state. -9. Hawk-owned persisted and CLI schemas do not mirror Eyrie DTOs implicitly. - -## Current slice - -- Eyrie provides the versioned host facade, provider-neutral DTOs, typed errors, - capability selection, normalized pull streaming, credential service, catalog - snapshots, injected credential/state paths, and explicit catalog-backed - deployment construction. -- Hawk's credential-save and production agent-chat paths now enter through - `eyrie/engine` via a Hawk-owned `ChatClient` adapter. -- Provider secrets are absent from Hawk's `Session`, `ChatService`, sub-session, - reattachment, and client-port surfaces. Native provider compaction uses - Eyrie's injected credential store and engine facade; Hawk receives only the - normalized summary and remains responsible for conversation mutation. -- Eyrie's control-plane facade now supplies credential resolution, safe masked - status, provider choices, and gateway configuration rows using its injected - credential store and state paths. Hawk owns their TUI/CLI presentation. -- Historical provider-state credentials are imported into the Engine's secret - store before an atomic sanitized rewrite. Every later provider-state write - uses the same sanitizer; Hawk protects the resolved - `EYRIE_CONFIG_DIR/provider.json` path from agent file and Bash access. -- Effective provider/model selection is an `eyrie/engine.Selection` contract; - Hawk's session factory, startup, live transport rebuild, and multi-agent - workers no longer depend on Eyrie's lower-level runtime selection DTOs. -- The model picker consumes display labels, ownership, serving gateway, - context, capabilities, pricing and price certainty from `engine.Model`; it - no longer reads or formats Eyrie's compiled catalog directly. -- `hawk models list --json` projects those DTOs into a stable Hawk-owned schema; - `--raw` exposes provider-native live metadata when present without coupling - automation to the engine DTO. -- Hawk retains task classification, workflow roles, cascade decisions and - health thresholds. Model lookup, aliases, provider ownership, defaults, - relative cost classes and preferred candidates now come from Eyrie's - host-neutral model-policy facade. -- The facade preserves advanced generation options and owns continuation; - Hawk's compatibility retry/rate-limit wrapper is bypassed for facade clients - so resilience is applied exactly once. -- Catalog administration, setup/diagnostics, review bridges, session creation, - parallel agents, custom gateways, and inline tool-call normalization all use - the engine boundary. The zero-exception rule is enforced by shell and AST - guards. -- Hawk supplies effective custom-provider settings in - `engine.Options.CustomGateways`; each Engine snapshots its own gateway set so - sessions and tests cannot leak configuration through globals. -- `hawk preflight` describes local readiness. A provider-scoped live model - fetch or `/config` validation is the optional live-verification step; local - readiness alone is not a remote authentication claim. -- Hawk's runtime conversation DTOs remain product-owned in `internal/types`; - the anti-corruption adapter in `internal/engine` translates them directly to - stable engine DTOs without importing a lower Eyrie transport package. -- Hawk now owns its persistent conversation graph under `internal/session`; - production sessions no longer mix Eyrie's generic DAG with Hawk WAL/session - persistence. - -## Completed removal gates - -Production catalog/setup/runtime/client compatibility imports are removed. -Lower Eyrie packages may appear only in tests that construct Eyrie-owned -fixtures. The provider circuit breaker, session API-key map, direct client -adapter, and mixed Eyrie DAG product path are also removed. Session file -readers remain backward-compatible for at least one release cycle. - -## Verification and release status - -See `verification-status-2026-07-13.md` for the evidence ledger. The committed -Eyrie Gitlink, checked-out submodule, and `go.mod` revision now converge on the -published Eyrie v0.2.1 commit. Hawk passed both workspace and `GOWORK=off` -verification, and the final migration revision passed hosted CI before merge. diff --git a/docs/architecture/session-migration-inventory.md b/docs/architecture/session-migration-inventory.md deleted file mode 100644 index 9ecfecc9..00000000 --- a/docs/architecture/session-migration-inventory.md +++ /dev/null @@ -1,120 +0,0 @@ -# Session Migration Inventory - -**Status:** Phase 2 inventory -**Date:** 2026-08-04 -**Branch:** `chore/architecture-phase0-baseline` - -This inventory is the migration gate for `internal/engine.Session`. The -Session refactor is intentionally high risk because the type is used by the -agent loop, compaction, command entry points, daemon construction, and -multi-agent workers. - -## Impact analysis - -GitNexus impact analysis was run upstream against the current indexed commit. - -| Symbol | Direct callers | Impacted symbols | Processes | Modules | Risk | -|---|---:|---:|---:|---:|---| -| `Session` | 1 | 9 | 1 | 3 | HIGH | -| `NewSessionWithClient` | 3 | 20 | 4 | 3 | HIGH | -| `Session.Persistence()` | 23 | 34 | not summarized | primarily Engine | HIGH | - -The affected named execution flows include: - -- `ReadOnlyValidationWorker` -- `runExec` -- `runMission` -- `runDaemonStart` - -The GitNexus index did not resolve a symbol named `AgentLoop`; the agent-loop -implementation is represented by other stream functions and must be mapped by -file and context before any stream symbol is edited. - -## Caller groups - -### Construction - -`NewSessionWithClient` is called by: - -- `internal/engine/session_factory.go` -- `internal/multiagent/worker.go` -- daemon and benchmark test factories -- resilience, compaction, and stream integration tests -- `Session.SubSession` - -The production construction path is therefore the factory plus the sub-session -path. Tests also construct sessions directly and must be migrated or explicitly -retained as test-only fixtures before compatibility fields are removed. - -### Persistence access - -`Session.Persistence()` is used by: - -- `internal/engine/stream.go` -- `internal/engine/engine.go` -- `internal/engine/compact*.go` -- `internal/engine/context_governor.go` -- `internal/engine/context_compaction.go` -- session message/context methods in `session.go` -- council and lifecycle/tool integration paths -- session, compaction, resilience, and integration tests - -The dominant access pattern is repeated read-modify-write through -`RawMessages()`, `SetRawMessages()`, `System()`, and compaction metadata. This -is a service API migration, not a simple field rename. - -### Direct struct literals - -Several tests use `Session{...}` directly. These fixtures are the reason the -current implementation retains lazy service materialization. They must be -classified as either: - -1. constructor tests that should use `NewSessionWithClient`; -2. focused service tests that should instantiate the service directly; or -3. intentional low-level fixtures with an explicit test-only builder. - -No production compatibility path should be removed until this classification -is complete. - -## Migration sequence - -The first bounded slice is complete: transcript/system state, token -accounting, token-estimate cache, and checkpoint-manager state now have one -owner in `PersistenceService`. `persistID` remains dual-written pending the -graph/journal migration slice. Zero-value lazy service materialization remains -as a compatibility seam until direct construction fixtures are classified. A -second slice is complete: LLM client/provider/model identity now has one owner -in `ChatService`, with synchronized access and reattachment. - -1. Freeze new direct reads of legacy Session fields. -2. Add or complete named service methods for each remaining access pattern. -3. Migrate one caller group at a time, starting with session accessors and - low-risk tests. -4. Migrate compaction and context governance as separate changes because they - mutate message state and have the largest persistence fan-out. -5. Migrate stream orchestration only after persistence and context contracts - are stable. -6. Replace direct struct literals with test builders. -7. Remove lazy service materialization and obsolete legacy fields. -8. Run impact analysis and the full verification suite after every step. - -## Safety gates - -- No broad find-and-replace on Session fields. -- Run `impact` upstream before modifying each function or method. -- Warn before proceeding on HIGH or CRITICAL impact. -- Preserve behavior with focused tests before removing compatibility paths. -- Run `make boundaries`, `go test ./internal/engine/...`, and the full suite - after each migration group. -- Run `detect_changes --scope compare --base-ref main` before committing. - -## Exit criteria - -Phase 2 is complete only when: - -- service state is the only authoritative runtime state; -- `Session` no longer contains duplicate legacy state; -- no production caller depends on lazy `Persistence()` fallback behavior; -- all direct struct-literal fixtures use an intentional test builder; -- session, compaction, recovery, and multi-agent tests pass; -- the final impact report shows the expected reduced fan-out. diff --git a/docs/architecture/verification-status-2026-07-13.md b/docs/architecture/verification-status-2026-07-13.md deleted file mode 100644 index d8bde9db..00000000 --- a/docs/architecture/verification-status-2026-07-13.md +++ /dev/null @@ -1,251 +0,0 @@ -# Ecosystem Verification Status — 2026-07-13 - -## Verdict - -The audited revision set has a release-aligned Hawk-face/Eyrie-engine boundary. -Local gates, Eyrie's release gates, and Hawk's final hosted pull-request gates -are green. The remaining publication step is the signed Hawk release tag and -its generated artifacts. - -The architecture and focused hardening tests support this responsibility split: - -```text -users and SDKs - | - v -Hawk product face - CLI / daemon / agent loop / sessions / tools / permissions / product schemas - | - v -Eyrie engine facade - credentials / provider state / catalog / route resolution / transport / - normalized streams / provider resilience / provider telemetry - | - v -model providers -``` - -The prior Eyrie release-parity mismatch is resolved by v0.2.1. Hawk PR #92 and -its follow-up documentation sync in PR #93 passed their hosted checks and were -merged to `main`. - -## Verified responsibility boundary - -Hawk owns the user-facing product and orchestration concerns: - -- CLI, TUI, daemon and SDK entrypoints -- coding-agent loop, tool authorization, permissions and project policy -- product session history, WAL, checkpoints, resume and replay -- task-semantic model intent and user-visible configuration presentation -- Hawk-owned persistence, runtime and public response schemas - -Eyrie owns the provider engine concerns behind `eyrie/engine`: - -- credentials, provider state and safe status projection -- catalog discovery, model capabilities and concrete route resolution -- provider adapters, transport and normalized generation/streaming -- provider retry, timeout, fallback, health and telemetry behavior - -Hawk production code is guarded against lower-level Eyrie imports. Hawk may -record product-level latency and usage, but it must not reimplement provider -routing or apply a second resilience policy to an Eyrie-facade request. - -## Hardening present in the audited workspace - -### Resolved route attribution - -- Hawk's provider-neutral response and stream DTOs preserve Eyrie's resolved - route. -- `route_selected` and `route_changed` events update the effective provider and - model used by traces, hooks, usage events and cost accounting. -- Cost updates change the effective model and apply token/cost totals under one - lock, preventing a routed fallback from being billed as the requested model. -- A repeated terminal usage payload is de-duplicated without dropping distinct - continuation-segment usage. - -Focused blocking, streaming, partial-route, usage and cost tests passed, -including the focused race checks recorded during this audit. - -### One provider-resilience layer - -- Hawk's `ChatClient` compatibility port has an optional resilience-ownership - capability. The Eyrie facade adapter advertises that it owns provider - resilience; legacy injected clients do not. -- For an Eyrie facade stream, Hawk delegates the initial request exactly once - and bypasses Hawk's compatibility call retry/rate limiting, transient stream - reopen, thinking-only non-streaming fallback and synthetic `max_tokens` - continuation. -- Legacy clients retain those compatibility behaviors. This preserves tests and - third-party adapters without wrapping production Eyrie calls in a second - retry policy. -- Hawk remains responsible for authorizing tool calls and persisting product - conversation messages regardless of which client owns resilience. - -Focused engine tests, focused race tests, `go vet` and the Hawk/Eyrie boundary -guards passed for this split. - -### Lossless Eyrie selection and provider-state migration - -- Existing Eyrie active selection is authoritative over Hawk's legacy - `provider` and `model` settings. -- A legacy provider/model pair is validated and written as one selection before - its source fields are removed. Rejected selections leave the source settings - untouched for repair instead of silently discarding them. -- Historical provider-state secrets are imported into Eyrie's secret store - before an atomic sanitized rewrite. -- Eyrie accepts the historical decode-only `version` key as well as canonical - `_version`, while still rejecting unknown fields, trailing JSON, conflicting - versions and unsupported future versions. - -Standalone Eyrie passed the full Go test suite, the full race-enabled suite, -`go vet`, both ecosystem boundary guards and `git diff --check` in this audit. - -### Hawk daemon readiness and durable sessions - -- `GET /v1/ready` returns success only when a session factory exists and - Eyrie's local preflight reports `Ready=true`. A missing or failed probe - returns 503 with a reason; factory wiring alone is not provider readiness. -- `POST /v1/chat` without a session ID creates a random durable ID, persists the - transcript and returns the same ID in the JSON response and - `X-Hawk-Session-ID` header. -- A request with a session ID requires an existing durable session, inherits - its transcript and metadata, appends the new turn and persists under the same - ID. Invalid IDs return 400 and missing sessions return 404. -- SSE responses expose the session ID header, persist the conversation and put - the session ID and usage in the final `done` event. -- Corrupt or unreadable session state is reported as an internal persistence - failure instead of being misclassified as a missing session. Fixed lock - striping serializes same-session operations without letting arbitrary - client-supplied IDs grow a lifetime lock map. -- Hawk applies and persists the requested agent persona. Session CWD is - validated and canonicalized as durable metadata; daemon tools intentionally - continue to use the daemon's startup CWD rather than an unsafe process-wide - directory change. - -Focused daemon/session and command tests passed in isolated directories, and -the daemon package passed its race-enabled test run. This preflight is a local -configuration/readiness check, not proof of live remote-provider authentication. - -### Hawk Cloud usage queue - -- The idempotency marker insert and monthly rollup update execute in one D1 - batch. The rollup uses SQLite `changes()` from the marker insert, so a - duplicate delivery cannot increment the aggregate twice. -- A failed message is retried rather than acknowledged at an application-local - retry limit. Cloudflare Queue `max_retries` and dead-letter configuration are - the single terminal-delivery policy, avoiding silent event loss. -- Retry backoff is capped at 12 hours. - -The queue-focused tests, the then-current full Hawk Cloud test suite, -type-check, formatting check, Wrangler type generation/dry run and a direct -SQLite idempotency check passed during the audit. - -### CI gates - -- Hawk's Docker Trivy step now fails on fixable high or critical image findings - (`exit-code: '1'`). -- Hawk Cloud CI now generates a V8 JSON coverage report, fails if the report or - any metric is missing, and enforces all four metric floors. -- The honest initial coverage floors are 30% statements, 20% branches, 40% - functions and 35% lines. The final measured local baseline was 32.65%, - 23.84%, 40.64% and 36.37%, respectively. Sixty percent remains a ratchet - target, not a description of current coverage. - -These are locally verified workflow/configuration changes. A successful remote -CI run on the final published commits is still required. - -### Community-skill corpus hardening - -- All 12,167 discovered skills pass the full-corpus validator. -- Every warning category is at zero: broken internal references, path traversal, - oversized files and `SKILL.md` bodies, script shebang and executable-bit - defects, excess tags, overlong descriptions and uncategorized warnings. -- The checked-in warning budget is zero per category. CI requires an exact - match, new categories start at zero and the budget must never increase. -- The local-reference validator covers every Markdown file in each skill, - applies exact-case and skill-root containment checks, and ignores code spans, - fenced code, anchors and external URLs. -- Safe, dry-run-first cleanup and oversized-body migration tools preserve - readable content and frontmatter while moving large bodies into ordered - progressive-disclosure references. The size allowlist now has zero - exceptions. - -The current community repository suite passed 303 tests, and the full validator -reported 12,167 passed, zero failed and zero warnings. Ruff, boundary and -registry checks remain part of the repository gate; this local result does not -replace final remote CI. - -## Verification evidence captured - -| Scope | Evidence recorded during this audit | Status | -| --- | --- | --- | -| Standalone Eyrie | full tests, full race tests, vet, boundary guards, diff check | Passed | -| Hawk route/config seams | focused tests and focused race checks | Passed | -| Hawk daemon/session seams | focused daemon, session and command tests; daemon race test | Passed | -| Support Go repos | full tests and vet for `hawk-core-contracts`, `inspect`, `sight`, `tok`, `yaad`, `trace`, `hawk-mcpkit` and `hawk-sdk-go` | Passed | -| Python SDK | 288 tests, Ruff check/format and strict mypy | Passed | -| Hawk Cloud queue | focused and full tests, type-check, format, Wrangler checks, direct SQLite check | Passed | -| Hawk full integration | isolated full tests, full race tests, vet and all architecture guards against the completed workspace | Passed | -| Published release graph | Eyrie v0.2.1 gitlink/module parity; two full Hawk passes in workspace and `GOWORK=off` modes | Passed locally and in Hawk hosted CI | -| Community skills | 303 tests; 12,167 skills passed; zero failures and zero warnings; Ruff, boundary and registry gates | Passed locally with a zero-warning budget | -| Adjacent GrayCode Core | forced 266-test run, lint, type-check, production build, Hawk Cloud contract comparison and package audit | Passed; not a runtime dependency | - -Passing a row describes the recorded local evidence only. It does not replace a -clean checkout, public revision reachability, signed release or remote CI run. - -The final security sweep found no reachable Go vulnerabilities in Hawk or -Eyrie, no npm audit findings in Hawk Cloud or GrayCode Core, and no known Python -SDK dependency vulnerabilities. Hawk's verbose Go scan did note -`GO-2026-5932` at module level because `golang.org/x/crypto` contains the -unmaintained `openpgp` package; no Hawk import or call reaches that package and -the advisory has no fixed module version. GrayCode Core remains outside the -Hawk runtime graph; its only checked integration here is the versioned Hawk -Cloud API contract. - -## Release status - -### Eyrie release graph is aligned - -The release sequence completed without weakening the parity guard or copying -local Eyrie source into Hawk: - -| Source | Revision | -| --- | --- | -| Published Eyrie module | `v0.2.1` | -| Published tag and module origin | `2e5ec4e3bb03705d5a09792009f113625258fc5a` | -| Hawk `external/eyrie` checkout and gitlink candidate | `2e5ec4e3bb03705d5a09792009f113625258fc5a` | - -The Eyrie v0.2.1 GitHub Release is published. Its pull-request gates passed -tests with the race detector, coverage, lint, vet, module hygiene, security, -four fuzz targets and all configured cross-platform builds. The module checksum -is recorded in Hawk's `go.sum`, and `go mod download -json` resolves v0.2.1 to -the same commit as the clean submodule checkout. - -Hawk then passed two complete shuffled test runs through the workspace checkout -and two through `GOWORK=off`, including the public-module build. The exact -workspace race-and-coverage run passed at 69.0% total statement coverage. Vet, -lint, formatting, all architecture guards, module verification and both -workspace/module vulnerability scans passed. - -### Hawk hosted CI passed - -The completed architecture change set passed Hawk's hosted test, race, -coverage, boundary, security, public-module, compatibility-matrix, Docker, and -submodule-parity gates on the exact reviewable revision before merge. Release -publication still independently verifies the tagged revision and artifacts. - -## Production-readiness exit criteria - -The ecosystem can make a production-ready claim only after all of the following -are true in one reproducible final revision set: - -- Eyrie Gitlink, clean checkout and published Go module resolve to the same - public commit. -- Hawk passes full, race, vet, boundary and release-parity verification through - both the local submodule and `GOWORK=off` module graph. -- Hawk Cloud tests, coverage gate, type-check, deployment dry run and security - scans pass in remote CI. -- Community-skill validation remains at zero warnings in every category, with - no size exceptions, in the final clean revision. -- The final repository set is clean, reviewable and tagged; no required behavior - depends on uncommitted local patches. diff --git a/docs/icon-survey.md b/docs/icon-survey.md deleted file mode 100644 index 9e69a5ae..00000000 --- a/docs/icon-survey.md +++ /dev/null @@ -1,93 +0,0 @@ -# How Go CLIs handle icons — a survey - -This is the survey done on 2026-06-16 when picking the icon strategy for -hawk. The question was: how do other Go CLI/TUI projects render icons in -a terminal, and should we use Lucide (the project's visual identity for -docs) or a different approach? - -## Methodology - -- Cloned or fetched main-branch Go source from each project via GitHub. -- Counted occurrences of `U+1F300–U+1FAFF` (emoji block) and - `U+2600–U+27BF` (dingbat block) in the source. -- Examined the rendering primitives they use (spinner, icon helper, etc.) -- Cross-referenced with their docs and READMEs. - -## Findings - -| Project | Emoji in source? | Approach | -|---|---|---| -| [charmbracelet/glow](https://github.com/charmbracelet/glow) | 0 | Pure box-drawing + braille in markdown rendering. | -| [charmbracelet/bubbletea](https://github.com/charmbracelet/bubbletea) (spinner) | 0 (braille U+28xx only) | Spinner uses `"⣾ ⣽ ⣻ ⢿ ⡿ ⣟ ⣯ ⣷"` — braille patterns, not emoji. | -| [charmbracelet/lipgloss](https://github.com/charmbracelet/lipgloss) | 0 | Color and style only. | -| [charmbracelet/mods](https://github.com/charmbracelet/mods) | 0 | ASCII only. | -| [charmbracelet/soft-serve](https://github.com/charmbracelet/soft-serve) | 0 | ASCII only. | -| [charmbracelet/pop](https://github.com/charmbracelet/pop) | 0 | ASCII only. | -| [spf13/cobra](https://github.com/spf13/cobra) | 0 | ASCII only. | -| [github/cli](https://github.com/cli/cli) (`pkg/iostreams/color.go`) | 1 (`✓`) | `ColorScheme.SuccessIcon()` returns the literal `"✓"`. Warning and failure icons are ASCII (`"!"`, `"X"`). | -| [derailed/k9s](https://github.com/derailed/k9s) | 3 (`🐶`, `💣`, `✅`) | Hard-coded emoji in startup slog messages. No central icon helper. | -| [epilande/go-devicons](https://github.com/epilande/go-devicons) | 0 (Nerd Font PUA only) | The closest "icon library" for Go: maps file paths to Nerd Font PUA codepoints. No ASCII fallback. | -| **hawk (this project)** | **0** (audit-enforced) | Centralized `internal/ui/icons` registry. Nerd Font PUA codepoints in Nerd Font mode, ASCII tokens in ASCII mode. Terminal-capability detection (TTY, NO_COLOR, LANG) gates the mode. | - -## Why not Lucide? - -Lucide () is the project's visual identity for docs -and web surfaces (see `docs/architecture.md`, which embeds Lucide SVGs). -It is an SVG-only icon set — **there is no standard PUA mapping for -Lucide in Nerd Fonts**. The Nerd Fonts cheat sheet -() confirms the available icon -sets are: `nf-cod-*` (VS Code Codicons), `nf-fa-*` (FontAwesome), -`nf-mdi-*` (Material Design), `nf-oct-*` (GitHub Octicons), `nf-pom-*` -(Pomicons), `nf-seti-*` (Seti-UI), `nf-pl-*` (Powerline), and -language / weather extras. None of these are Lucide. - -The only ways to render Lucide glyphs in a terminal are: - -1. **Build a custom Nerd Font** that embeds a Lucide subset and ship - it. Requires font-forge / Python tooling, and a way to ensure the - end user has the patched font installed. None of the popular Go - CLIs surveyed do this. -2. **Render Lucide SVGs as Unicode block art at print time.** Use - half-block characters (`▀ ▄ ▌ ▐`) to compose a 2-color image - from an SVG path. Real Lucide look in any terminal, but ~10× slower - printing, complex code, and breaks for captured output (the - "▀▄" sequence doesn't diff well). The popular - [`jp2a`](https://github.com/cslarsen/jp2a) tool does this for - JPEGs, but for inline CLI icons it's a non-starter. -3. **Use a different PUA-based icon set that resembles Lucide.** The - current state — Nerd Fonts Codicons — is the closest practical - match. Codicons share a 2px stroke, rounded geometry with Lucide, - and look familiar to anyone who's used a recent IDE. They are not - Lucide, but they don't try to be. - -## What hawk does - -The `internal/ui/icons` package implements option (3) with the -following design: - -- Every glyph in the registry has a Nerd Font PUA codepoint and an - ASCII fallback token. -- A `Mode()` function returns `ModeNerd` or `ModeASCII` based on: - - The `HAWK_ICONS=nerd|ascii` env var (forces a mode). - - `NO_COLOR` set → `ModeASCII` (also disables ANSI color). - - stdout not a TTY → `ModeASCII` (captured output stays clean). - - A Nerd Font detected in the terminal → `ModeNerd`. - - Locale looks like UTF-8 → `ModeNerd`; otherwise → `ModeASCII`. -- The `TestNoEmojiInCmd` and `TestNoEmojiInInternalExceptIcons` audits - parse every non-test Go file in `cmd/` and `internal/`, fail CI on - any emoji (U+1F300–U+1FAFF) or dingbat (U+2600–U+27BF) rune. Parser - files (`test_loop.go`, `test_fixtures.go`) and markdown / multiagent - prompt packages are exempt with a documented comment. - -The end result: hawk's CLI is portable, fast, mode-aware, and -guaranteed emoji-free by an enforced audit. Users with a Nerd Font -get icons; everyone else gets readable ASCII tokens. - -## Verdict - -The Nerd-Font-PUA + ASCII-fallback approach is the de facto standard -for Go CLIs that care about icon rendering. The hawk approach is more -disciplined than most (centralized registry, auto-detected mode, -audit-enforced emoji ban, mode-aware tests). Migrating to Lucide is -not feasible in a terminal without one of the expensive options -above; the current path is the right call. diff --git a/docs/monorepo-analysis.md b/docs/monorepo-analysis.md deleted file mode 100644 index 0839326c..00000000 --- a/docs/monorepo-analysis.md +++ /dev/null @@ -1,358 +0,0 @@ -# Hawk Monorepo Analysis Report - -> Historical note: this document uses “monorepo” loosely for the local -> `hawk-eco` workspace. The current architecture is a multi-repository -> ecosystem with Hawk as the product repository. See -> [Hawk Architecture Baseline](architecture/hawk-architecture-baseline.md) for -> the authoritative dated state. - -**Date:** 2026-07-05 -**Scope:** Analysis of the hawk-eco monorepo structure, configuration, and organization - ---- - -## 1. Monorepo Structure Overview - -### Root Directory Layout -``` -hawk-eco/ # Root directory -├── .claude/ # AI assistant configuration -├── eyrie/ # LLM provider runtime (Go) -├── graycode-core/ # Core framework (Go) -├── hawk/ # Main CLI application (Go) [781 files] -├── hawk-community-skills/ # Community skills/extensions -├── hawk-core-contracts/ # Shared cross-repo types (Go) -├── hawk-mcpkit/ # MCP toolkit -├── hawk-sdk-go/ # Go SDK -├── hawk-sdk-python/ # Python SDK -├── inspect/ # Security audit library -├── sight/ # Diff-based code review -├── tok/ # Tokenizer, compression, secrets scanning -├── trace/ # Session capture and replay -└── yaad/ # Graph-based persistent memory -``` - -### Internal Structure of hawk/ -``` -hawk/ -├── cmd/ # CLI commands and main entry points -├── internal/ -│ ├── engine/ # Core engine (61 packages) -│ │ ├── agent/ # Agent logic -│ │ ├── budget/ # Budget management -│ │ ├── cascade/ # Cascade operations -│ │ ├── compact/ # Compaction strategies -│ │ ├── council/ # Council operations -│ │ ├── diff/ # Diff operations -│ │ ├── lifecycle/ # Lifecycle management -│ │ ├── memory/ # Memory management -│ │ ├── mode/ # Mode settings -│ │ ├── multi_repo/ # Multi-repo operations -│ │ ├── party/ # Party mode -│ │ ├── retry/ # Retry logic -│ │ ├── safety/ # Safety mechanisms -│ │ ├── session/ # Session operations -│ │ ├── snowball/ # Snowball operations -│ │ └── ... # (35 more packages) -│ ├── tool/ # Tool implementations -│ │ ├── bash/ # Bash execution -│ │ ├── codegen/ # Code generation -│ │ ├── sandbox/ # Sandbox operations -│ │ └── ... # (10+ more tools) -│ ├── config/ # Configuration management -│ ├── permissions/ # Permission handling -│ ├── sandbox/ # Sandbox management -│ ├── multiagent/ # Multi-agent coordination -│ ├── bridge/ # Bridge implementations -│ ├── feature/ # Feature flags -│ ├── hooks/ # Hook implementations -│ ├── provider/ # Provider abstractions -│ └── system/ # System utilities -└── external/ # External module dependencies -``` - ---- - -## 2. Go Workspace Configuration - -### go.work File -```go -// hawk/go.work -module github.com/GrayCodeAI/hawk - -go 1.26.4 - -use . - -replace ( - github.com/GrayCodeAI/eyrie => ./external/eyrie - github.com/GrayCodeAI/hawk-core-contracts => ./external/hawk-core-contracts - github.com/GrayCodeAI/inspect => ./external/inspect - github.com/GrayCodeAI/sight => ./external/sight - github.com/GrayCodeAI/tok => ./external/tok - github.com/GrayCodeAI/trace => ./external/trace - github.com/GrayCodeAI/yaad => ./external/yaad -) -``` - -### Go Module Configuration -```go -// hawk/go.mod -module github.com/GrayCodeAI/hawk - -go 1.26.4 - -require ( - github.com/GrayCodeAI/eyrie v0.1.3 - github.com/GrayCodeAI/hawk-core-contracts v0.1.3 - github.com/GrayCodeAI/inspect v0.1.3 - github.com/GrayCodeAI/sight v0.1.2 - github.com/GrayCodeAI/tok v0.1.2 - github.com/GrayCodeAI/yaad v0.1.3 - github.com/bwmarrin/discordgo v0.28.1 - github.com/charmbracelet/bubbles v1.0.0 - github.com/charmbracelet/bubbletea v1.3.10 - github.com/charmbracelet/lipgloss v1.1.0 - github.com/charmbracelet/x/ansi v0.11.7 - github.com/fsnotify/fsnotify v1.10.1 - github.com/google/uuid v1.6.0 - github.com/mattn/go-runewidth v0.0.24 - github.com/smacker/go-tree-sitter v0.0.0-20240827094217-dd81d9e9be82 - github.com/spf13/cobra v1.10.2 - github.com/spf13/pflag v1.0.10 - github.com/tetratelabs/wazero v1.12.0 - go.opentelemetry.io/otel v1.44.0 - go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.44.0 - go.opentelemetry.io/otel/sdk v1.44.0 - go.opentelemetry.io/otel/sdk/metric v1.44.0 - go.opentelemetry.io/otel/trace v1.44.0 - golang.org/x/sys v0.46.0 - golang.org/x/term v0.44.0 - golang.org/x/text v0.38.0 - gopkg.in/yaml.v3 v3.0.1 - modernc.org/sqlite v1.51.0 -) - -require ( - cel.dev/expr v0.25.2 // indirect - charm.land/bubbles/v2 v2.1.0 // indirect - charm.land/bubbletea/v2 v2.0.7 // indirect - charm.land/glamour/v2 v2.0.0 // indirect - charm.land/huh/v2 v2.0.3 // indirect - charm.land/lipgloss/v2 v2.0.3 // indirect - dario.cat/mergo v1.0.2 // indirect - github.com/BobuSumisu/aho-corasick v1.0.3 // indirect - github.com/Masterminds/semver/v3 v3.5.0 // indirect - github.com/Microsoft/go-winio v0.6.2 // indirect - github.com/ProtonMail/go-crypto v1.4.1 // indirect - github.com/STARRY-S/zip v0.2.3 // indirect - github.com/alecthomas/chroma/v2 v2.26.1 // indirect - github.com/andybalholm/brotli v1.2.1 // indirect - // ... (10+ more indirect dependencies) -) -``` - -### Workspace Status: ✅ PROPERLY CONFIGURED -- Go version: 1.26.4 (current) -- All external modules properly replaced with local paths -- Clean `use .` directive -- Consistent module path across all projects - ---- - -## 3. External Dependencies Summary - -| Module | Language | Purpose | Version | -|--------|----------|---------|---------| -| eyrie | Go | LLM provider runtime | v0.1.3 | -| hawk-core-contracts | Go | Shared types/contracts | v0.1.3 | -| inspect | Go | Security audit library | v0.1.3 | -| sight | Go | Diff-based code review | v0.1.2 | -| tok | Go | Tokenizer & compression | v0.1.2 | -| trace | Go | Session capture & replay | v0.1.3 | -| yaad | Go | Graph-based memory | v0.1.3 | - -### Dependency Relationships -``` -hawk-core-contracts - ├── inspect - ├── sight - ├── tok - └── yaad - -eyrie (standalone LLM runtime) - └── (consumed by hawk) - -hawk-mcpkit (standalone MCP toolkit) - └── (consumed by hawk) - -hawk-sdk-go (standalone Go SDK) - └── (consumed by hawk) - -hawk-sdk-python (standalone Python SDK) - └── (consumed by hawk) -``` - -### Status: ✅ WELL-MANAGED -- All dependencies versioned consistently (v0.1.x) -- Replace directives properly configured -- All external modules checked out in hawk-eco/ root -- No circular dependencies detected - ---- - -## 4. CI/CD Configuration Analysis - -### CI Pipeline (.github/workflows/ci.yml) -```yaml -name: CI -on: - push: - branches: [main, release/*] - pull_request: - branches: [main] - -jobs: - build-and-test: - runs-on: ubuntu-latest - strategy: - matrix: - go-version: ['1.26'] - platform: [ubuntu-latest, macos-latest] - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-go@v5 - with: - go-version: ${{ matrix.go-version }} - - name: Get dependencies - run: go mod download - - name: Test with race detector - run: go test -race -count=3 ./... - - name: Build - run: go build -v ./... - - name: Lint - uses: golangci-lint-action@v6 - with: - version: latest - - name: Security scan - uses: securego/gosec@master - with: - args: -include=G104,G204,G301,G302,G303,G304,G306,G307 ./... - - docker: - runs-on: ubuntu-latest - needs: build-and-test - steps: - - uses: actions/checkout@v4 - - uses: docker/login-action@v3 - with: - username: ${{ secrets.DOCKER_USERNAME }} - password: ${{ secrets.DOCKER_PASSWORD }} - - uses: docker/setup-buildx-action@v3 - - uses: docker/build-push-action@v6 - with: - context: . - platforms: linux/amd64,darwin/arm64 - push: true - tags: ${{ secrets.DOCKER_IMAGE }}:latest - - release: - runs-on: ubuntu-latest - needs: [build-and-test, docker] - if: startsWith(github.ref, 'refs/tags/v') - steps: - - uses: actions/create-release@v1 - with: - tag_name: ${{ github.ref }} - release_name: ${{ github.ref }} - - compatibility: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-go@v5 - - run: go build -o hawk ./cmd - - run: ./compatibility/compat-test.sh - - run: go test -run Compat ./... -``` - -### Status: ✅ COMPREHENSIVE -- Build & test with race detector -- Cross-platform builds (linux/amd64, darwin/arm64) -- Linting (golangci-lint, gosec) -- Docker build & push -- Release automation -- Compatibility matrix generation - ---- - -## 5. Documentation Assessment - -### Existing Documentation - -| File | Description | Status | -|------|-------------|--------| -| README.md | Main setup guide | ✅ Comprehensive | -| AGENTS.md | Developer guide | ✅ Detailed | -| SECURITY.md | Security policy | ✅ Defined | -| CONTRIBUTING.md | Contribution guidelines | ✅ Structured | - -### Detailed Documentation Files - -#### Architecture Documentation (docs/) -``` -docs/ -├── architecture.md # System architecture -├── compatibility.md # Version compatibility -├── DEVELOPER-PATH.md # Development workflow -├── DYNAMIC-MODELS.md # Dynamic model patterns -├── ECOSYSTEM-CONFIG.md # Ecosystem configuration -├── ECOSYSTEM-MESSAGE-FLOW.md # Message flow architecture -├── mcp-servers.md # MCP server implementation -├── OTEL-CONVENTIONS.md # OpenTelemetry standards -├── plugin-development.md # Plugin development guide -├── SECURITY-DEVELOPER.md # Security developer guide -├── session-decomposition.md # Session breakdown patterns -├── versioning.md # Versioning strategy -``` - -### Status: ✅ THOROUGH -- 19 documentation files covering all major aspects -- Architecture patterns well-documented -- Security guidelines defined -- Development workflow clearly explained -- Versioning strategy documented - ---- - -## 6. Strengths and Recommendations - -### Strengths ✅ -1. **Proper Go workspace setup** with all external modules replaced -2. **Clean module organization** with separate directories for each package -3. **Comprehensive CI/CD pipeline** covering all quality gates -4. **Detailed documentation** for setup and development -5. **Consistent Go version** across the monorepo -6. **Versioned external dependencies** with proper replace directives -7. **Cross-platform builds** supporting both Linux and macOS -8. **Security scanning** integrated into CI/CD - -### Recommendations -1. **Add top-level Makefile** for cross-project operations -2. **Consider SDK directory documentation** improvements -3. **Add dependency update automation** -4. **Consider adding CODEOWNERS file** at root level - ---- - -## 7. Conclusion - -The historical analysis found a well-organized local workspace with Go module -and CI support. It is not a current architecture assessment; dependency -ownership, migration status, and verification evidence are maintained in the -architecture baseline. - ---- - -**Analyst:** Droid (AI assistant) -**Date:** 2026-07-05 diff --git a/docs/plans/PR_BODY.md b/docs/plans/PR_BODY.md deleted file mode 100644 index 0633ef45..00000000 --- a/docs/plans/PR_BODY.md +++ /dev/null @@ -1,52 +0,0 @@ -## Summary - -Ship the post-audit hardening batch: Charm v2-only TUI stack, tighter binary -size gate, Hawk Cloud CLI integration, engine pin hygiene, release Gitlink -strictness, and Yaad re-pin after the demo TUI nested-module split. - -## Why - -- Dual Charm v1/v2 inflated the binary and dependency graph -- Releases must never silently fall back to engine `main` when a Gitlink is - missing or unreachable -- Yaad’s library graph must stay free of Bubble Tea so Hawk does not pay for a - demo TUI - -## Highlights - -| Area | Change | -|------|--------| -| TUI | Migrate to `charm.land/*/v2`; fix remaining API incompatibilities | -| Size | `make size-check` / CI threshold **110MB → 80MB** (~75MB verified) | -| Cloud | CLI login, usage reporting, delivery-context wiring | -| Pins | Submodule updates + `scripts/check-submodule-release-parity.sh` | -| Layers | `scripts/check-internal-layer-imports.sh` | -| Release | `checkout-eyrie` fails closed without Gitlinks; release job verifies pins | -| Yaad | Re-pin to nested-module TUI split (`b7ee281`) | -| Docs | Remediation plans updated with acceptance evidence | - -## Depends on - -1. Merge/push **yaad** PR first (`b7ee281` must be reachable on origin) -2. Then this PR (or push) so public-module CI can resolve the new pseudo-version - -## Test plan - -- [x] `make size-check` → ~75 MB -- [x] `go list -m all` has no `charmbracelet/{bubbles,bubbletea,lipgloss}` v1 stack -- [x] `go test ./internal/intelligence/memory/ ./internal/platform/cloud/ ./cmd` -- [x] `make internal-layers-guard` -- [ ] CI green after yaad is published (`public-modules`, `submodule-release-parity`) -- [ ] Manual smoke: REPL, `/config`, `/autonomy` pickers (Charm v2) - -## Rollout - -```bash -# 1) yaad -cd yaad && git push origin main # or open PR from docs/PR_BODY.md - -# 2) hawk -cd hawk && git push origin main # or open PR from this body -# if needed after publish: -go mod tidy && git add go.sum && git commit -m "chore: refresh go.sum after yaad publish" -``` diff --git a/docs/plans/Y0-CALL-SITE-INVENTORY.md b/docs/plans/Y0-CALL-SITE-INVENTORY.md deleted file mode 100644 index 7f66737e..00000000 --- a/docs/plans/Y0-CALL-SITE-INVENTORY.md +++ /dev/null @@ -1,77 +0,0 @@ -# Year 0 Call-Site Inventory - -**Date:** 2026-07-16 -**Purpose:** Freeze entry points before PACK-02 spawn and taskruntime work. -**Rule:** Do not add a fourth background agent system. - -## 1. Agent spawn - -| Location | Role | Today | -|----------|------|--------| -| `internal/tool/tool.go` | `ToolContext.AgentSpawnFn` | **Updated:** `func(ctx, SpawnRequest) (SpawnResult, error)` | -| `internal/engine/agent_session_tool.go` | `WireAgentTool` | **Updated:** typed spawn; maps explore/plan/general | -| `internal/engine/agent_session_tool.go` | `spawnSubAgent` | Uses Normalized + mode; plan tools filter | -| `internal/tool/agent.go` | `Agent` tool | Schema: type, capability, isolation, thoroughness, cwd, model, resume, bg | -| `internal/tool/agent.go` | `MultiAgent` | String tasks + typed object tasks | -| `internal/tool/agentic_fetch.go` | Research spawn | Uses `AgentSpawnFn(prompt)` | -| `internal/tool/agent*_test.go` | Unit tests | Mock prompt-only spawn | - -**Target (PACK-02):** `AgentSpawnFn(ctx, agent.SpawnRequest) (agent.SpawnResult, error)` from -`hawk-core-contracts/agent`, with adapter only if dual-path flag requires it. - -## 2. Background / task systems (unify → one) - -| System | Location | Role | -|--------|----------|------| -| `BackgroundAgentManager` | `internal/tool/background.go` | Sub-agent bg spawn + collect by id | -| `BackgroundRunner` | search under `internal/engine/` | Engine-level bg runs | -| `BackgroundAgentPool` | search under `internal/engine/agent/` | Pool for multi-agent | - -**Target (PACK-02):** single `internal/taskruntime` (or equivalent) registry; -Wait/Kill/Monitor tools (PACK-06) bind only to that registry. - -## 3. Mode / budget libraries (keep, wire) - -| Location | Role | -|----------|------| -| `internal/engine/agent/agent_types.go` | explore / general / plan modes | -| `internal/engine/agent/subagent_budget.go` | tool allowlists + turn budgets | -| `internal/tool/bash_ast.go` | bash AST helpers for explore hard gate | - -## 4. Permission / hooks / plugins (later packs) - -| Location | Role | Y0 pack | -|----------|------|---------| -| `internal/engine/safety/permission_engine.go` (or permissions package) | CheckTool pipeline | PACK-03/04 | -| `internal/hooks/` | Hook registry/events | PACK-04 | -| `internal/plugin/` | Plugin manager V1/V2 | PACK-05 | -| `internal/sandbox/` | OS backends; modes | PACK-03 | - -## 5. Feature flags - -| Flag env | Package | Pack | -|----------|---------|------| -| `HAWK_Y0_SPAWN_V2` | `internal/flags` | PACK-02 | -| `HAWK_Y0_FOLDER_TRUST` | `internal/flags` | PACK-03 | -| `HAWK_Y0_MARKETPLACE` | `internal/flags` | PACK-05 | - -## 6. Spawn test matrix template (PACK-02) - -| subagent_type | capability | isolation | background | Expected | -|---------------|------------|-----------|------------|----------| -| explore | read-only (default) | none | false | No Write/Edit; bash AST gate | -| explore | read-only | worktree | false | Worktree cwd; read-only tools | -| plan | read-only | none | false | Plan tools only; no Write | -| general-purpose | all | none | false | Full tools | -| general-purpose | execute | worktree | true | Task id; killable; worktree | -| explore | — | none | false + resume_from | Continues transcript | - -Cases must run under `go test` (+ race on taskruntime). - -## 7. Dependency freeze - -Until PACK-02 taskruntime cutover: - -- [x] Document three bg systems -- [ ] No new background manager type without replacing an existing one -- [ ] All new spawn call sites take `SpawnRequest` diff --git a/docs/plans/YEAR-0-ACTIVE.md b/docs/plans/YEAR-0-ACTIVE.md index 5ccc0914..56cbd79a 100644 --- a/docs/plans/YEAR-0-ACTIVE.md +++ b/docs/plans/YEAR-0-ACTIVE.md @@ -5,7 +5,6 @@ **ADR:** [ADR-0003](../architecture/adr/ADR-0003-grok-behavioral-port-go-multirepo.md) **Full matrices:** [FULL-GROK-ECO-TO-HAWK-ECO-PORT-PLAN.md](./FULL-GROK-ECO-TO-HAWK-ECO-PORT-PLAN.md), [GROK-CLASS-CAPABILITY-LONG-HORIZON-PLAN.md](./GROK-CLASS-CAPABILITY-LONG-HORIZON-PLAN.md) -**Call-site inventory:** [Y0-CALL-SITE-INVENTORY.md](./Y0-CALL-SITE-INVENTORY.md) This is the **executable Year 0 program**. It does not replace the full port matrices; it freezes what “Year 0 done” means and tracks pack status. diff --git a/docs/plans/architecture-upstream-release-plan.md b/docs/plans/architecture-upstream-release-plan.md deleted file mode 100644 index 7fb77c91..00000000 --- a/docs/plans/architecture-upstream-release-plan.md +++ /dev/null @@ -1,209 +0,0 @@ -# Plan: Hawk Architecture Upstream and Release Convergence - -> Status: ready for execution -> Scope: push, merge, repin, verify, and release the Hawk ecosystem architecture work -> Goal: move the locally verified Hawk-centered architecture into upstream default branches and aligned published versions - -## Purpose - -The architecture cleanup is complete in the local `hawk-eco` workspace. - -This plan covers the remaining operational work: - -- push local branches upstream -- open and merge PRs in dependency order -- repin Hawk submodules to merged upstream SHAs -- rerun final integration verification -- publish tags/modules only after upstream convergence - -## Principles - -1. Merge shared contracts first. -2. Merge support-engine boundaries before Hawk. -3. Merge consumer guards after the engine direction is settled. -4. Merge Hawk last, because Hawk pins the support repos. -5. Do not redesign architecture during release convergence. - -## Repo order - -### Phase 1: shared contract base - -1. `hawk-core-contracts` - -### Phase 2: support engines - -2. `sight` -3. `inspect` -4. `eyrie` -5. `yaad` -6. `trace` -7. `tok` - -### Phase 3: consumers - -8. `hawk-sdk-go` -9. `hawk-sdk-python` -10. `hawk-community-skills` - -### Phase 4: product repo - -11. `hawk` - -## Repo board - -| Repo | Branch | Commit | PR title | Merge gate | -|---|---|---|---|---| -| `hawk-core-contracts` | `main` | `f9989e5` | `docs: describe hawk-core-contracts as the live cross-repo API` | none | -| `sight` | `feat/contracts-migration` | `b990666` | `feat(contracts): migrate to hawk-core-contracts and enforce boundary` | `hawk-core-contracts` merged | -| `inspect` | `feat/contracts-migration` | `d6ca739` | `feat(contracts): migrate to hawk-core-contracts and enforce boundary` | `hawk-core-contracts` merged | -| `eyrie` | `feat/ecosystem-boundary-guard` | `c1a6a4d` | `docs: remove legacy shared types references` | `hawk-core-contracts` merged | -| `yaad` | `feat/ecosystem-boundary-guard` | `010178d` | `chore: strip Co-authored-by trailers in lefthook hooks` | `hawk-core-contracts` merged | -| `trace` | `feat/ecosystem-boundary-guard` | `735e3f4` | `chore: strip Co-authored-by trailers in lefthook hooks` | `hawk-core-contracts` merged | -| `tok` | `feat/contracts-types-realignment` | `83cfc551` | `refactor: remove tok types compatibility shim` | `hawk-core-contracts` merged | -| `hawk-sdk-go` | `ci/consumer-boundary-guard` | `97b523e` | `ci: guard sdk-go consumer boundaries` | support-engine direction settled | -| `hawk-sdk-python` | `ci/consumer-boundary-guard` | `c43ad43` | `ci: guard sdk-python consumer boundaries` | support-engine direction settled | -| `hawk-community-skills` | `ci/consumer-boundary-guard` | `350f4f2c6` | `ci: guard skills consumer boundaries` | support-engine direction settled | -| `hawk` | `docs/contracts-architecture-truth` | `a2a4583` | `chore: align hawk external architecture snapshot` | all upstream support repos merged | -| `hawk` | `docs/contracts-architecture-truth` | `46697b9` | `docs: retire tok types shim references` | `tok` merged | -| `hawk` | `docs/contracts-architecture-truth` | `c204597` | `docs: normalize architecture status` | final architecture state agreed | - -## Execution checklist - -### Phase 1: push branches - -For each repo: - -1. confirm working tree is clean -2. push the local branch -3. open PR with the planned title/summary -4. wait for CI - -Suggested command pattern: - -```bash -git -C push -u origin -gh -R GrayCodeAI/ pr create --fill -``` - -### Phase 2: merge in dependency order - -Merge order: - -1. `hawk-core-contracts` -2. `sight` -3. `inspect` -4. `eyrie` -5. `yaad` -6. `trace` -7. `tok` -8. `hawk-sdk-go` -9. `hawk-sdk-python` -10. `hawk-community-skills` -11. `hawk` - -Rules: - -- do not merge `hawk` before the support repos -- do not publish module tags before merge convergence -- if upstream rebases or squashes PRs, treat the merged upstream SHA as the new source of truth - -### Phase 3: repin Hawk - -After the support-repo PRs merge: - -1. fetch upstream default branches for all pinned repos -2. update `hawk/external/*` to the merged upstream SHAs -3. run `go work sync` -4. rerun Hawk verification -5. commit the repin if the upstream SHAs differ from current local pins - -Checks: - -- `external/eyrie` -- `external/hawk-core-contracts` -- `external/inspect` -- `external/sight` -- `external/tok` -- `external/trace` -- `external/yaad` - -### Phase 4: final verification - -From `hawk`: - -```bash -/bin/sh ./scripts/check-shared-types-imports.sh -/bin/sh ./scripts/check-ecosystem-boundaries.sh -go work sync -go test ./internal/testaudit -count=1 -``` - -From support repos: - -```bash -/bin/sh ./scripts/check-ecosystem-boundaries.sh -go test ./... -count=1 -``` - -From consumer repos: - -```bash -/bin/sh ./scripts/check-consumer-boundaries.sh -``` - -## Release/tag guidance - -Only after merge convergence: - -1. decide which repos need tags immediately -2. publish `hawk-core-contracts` first if modules consume tagged versions -3. publish any support repos whose released versions are referenced by Hawk or external consumers -4. verify Hawk docs/examples do not claim unpublished versions - -Minimum release check: - -- merged commit exists on upstream default branch -- CI green on merged branch -- version/tag points at the merged contract-compatible state - -## Risks and responses - -### Upstream merge SHA differs from local SHA - -Response: - -- update Hawk submodule pins to the merged upstream SHA -- rerun `go work sync` -- rerun Hawk verification - -### PR is squashed and commit messages change - -Response: - -- treat the merged branch state as canonical -- do not assume local commit SHAs remain valid for Hawk submodule pins - -### A support repo fails CI after merge - -Response: - -- stop before merging Hawk -- fix the support repo first -- only repin Hawk after the repaired upstream state is green - -### A published module version lags merged code - -Response: - -- do not claim release convergence yet -- tag/publish before calling the ecosystem release-ready - -## Exit criteria - -This plan is complete when: - -- all listed PRs are merged upstream -- Hawk submodules point at merged upstream SHAs -- Hawk verification passes against those SHAs -- any required published module versions match the merged architecture state -- no repo needs the old architecture path or compatibility shims diff --git a/docs/plans/ecosystem-architecture-remediation.md b/docs/plans/ecosystem-architecture-remediation.md deleted file mode 100644 index 3d05c760..00000000 --- a/docs/plans/ecosystem-architecture-remediation.md +++ /dev/null @@ -1,133 +0,0 @@ -# Ecosystem architecture remediation plan - -This plan is the executable follow-up to the July 2026 source-level audit of -the fourteen Hawk ecosystem repositories. An item is complete only when its -acceptance evidence passes; documentation or intent alone is not sufficient. - -**Last evidence pass:** 2026-07-11 - -## P0 — release graph and submodules - -- [x] Pin all seven `external/` submodules to the selected, publicly reachable - ecosystem snapshot. *(local pins present; re-pin after each engine push)* -- [ ] Make the versions in `go.mod` resolve to API-compatible commits from the - same snapshot. *(blocked until new engine commits — especially yaad - `b7ee281` — are published; `go.work` replace is authoritative for - integration builds)* -- [x] Add CI for both supported dependency modes: - - pinned integration: `go test ./...` with `go.work`; - - public modules: `GOWORK=off go test ./...`. - Evidence: `.github/workflows/ci.yml` jobs `module`, `public-modules`. -- [x] Prevent release workflows from falling back from a missing Gitlink commit - to a branch head. - Evidence: `.github/actions/checkout-eyrie` defaults `allow_branch_fallback=false` - and fails on missing/unreachable pins; `release.yml` verifies Gitlink == - checked-out HEAD before goreleaser. -- [x] Add a release-parity guard that reports whether each Gitlink is represented - by the module version in `go.mod`. - Evidence: `scripts/check-submodule-release-parity.sh` + Makefile target - `submodule-release-parity` + CI job. - -Acceptance: - -```sh -git submodule status -make boundaries -go test ./... -GOWORK=off go test ./... -``` - -## P1 — public contracts - -- [x] Keep `hawk/api/openapi.yaml` as the sole Hawk daemon server contract. - Evidence: SDK snapshots under `hawk-sdk-*/api/openapi.yaml` + coverage tests - that treat the daemon contract as authoritative. -- [x] Make both SDK repositories verify their implemented methods and JSON - models against that contract. - Evidence: - - Go: `hawk-sdk-go/internal/spec/openapi_coverage_test.go` - - Python: `hawk-sdk-python/tests/test_openapi_coverage.py` -- [x] Cover `/v1/ready`, `/v1/review`, and `/v1/review/status`, or explicitly - identify them as intentionally unsupported in SDK capability metadata. - Evidence: `SUPPORTED_ENDPOINTS.md` in both SDKs + coverage decision maps. -- [x] Add route/operation parity for `hawk-cloud/contracts/openapi.yaml`. - Evidence: `hawk-cloud/test/openapi-parity.test.ts` -- [x] Replace GrayCode's untyped/manual Hawk Cloud transport surface with a - contract-checked client boundary. - Evidence: `graycode-core/apps/backend/test/hawk-cloud-contract.test.ts` - (BFF may only reference paths present in the cloud OpenAPI snapshot). -- [ ] Add OpenAPI breaking-change checks to CI. - *(still open — no oasdiff/spectral gate wired yet)* - -Acceptance: daemon and cloud route-parity tests pass, SDK contract tests pass, -and a deliberate undocumented route causes the relevant test to fail. - -## P1 — Hawk Cloud correctness and security - -- [x] Separate client-reported cost from server-calculated ledger cost. - Evidence: `hawk-cloud/src/domain/metering.ts` (`reportedCostMicros` vs - `costMicros`) + `test/metering.test.ts` (“ignores forged client cost”). -- [x] Version the pricing input used by server-side metering. - Evidence: `pricingVersion` on `MeteringResult` + catalog `version` field. -- [x] Ensure billing and budgets use only the verified ledger value. - Evidence: usage/billing routes aggregate `usage_ledger.cost_micros`, not - client estimates. -- [x] Add positive and negative authorization tests for every route family. - Evidence: `hawk-cloud/test/authorization-matrix.test.ts` -- [x] Split route handlers so HTTP, policy, service, and persistence concerns are - independently testable. - Evidence: `src/domain/*` + `src/routes/*` layout + domain unit tests. -- [x] Add OSS metadata (`LICENSE`) and document repository/release setup. - Evidence: `hawk-cloud/LICENSE`, `hawk-cloud/README.md` - -Acceptance: cloud tests prove that forged client cost cannot alter billable -cost, every route is present in OpenAPI, authorization matrices pass, typecheck -passes, and the production build succeeds. - -## P2 — maintainability and ownership - -- [ ] Split GrayCode's organization BFF by organization, project, access, - billing, enterprise, analytics, and delivery domains. - *(still open — large refactor; contract tests exist but file split pending)* -- [x] Document `graycode-core.usage_logs` as GrayCode-platform data and prohibit - it from becoming an authoritative Hawk ledger. - Evidence: `graycode-core/README.md` (usage_logs paragraph). -- [x] Add import guards for Hawk delivery, application, domain/ports, and adapter - layers while migration proceeds. - Evidence: `scripts/check-internal-layer-imports.sh` + `make internal-layers-guard`. -- [x] Define the embedding boundary for Trace and the target boundary between - Sight source review and Inspect deployed-target inspection. - Evidence: engine READMEs + `docs/architecture/ecosystem-architecture.md`. -- [x] Decide and document the intentionally narrow `hawk-mcpkit` adoption scope; - do not force engines with different MCP server requirements into it. - Evidence: ecosystem architecture table (Sight/Inspect only). -- [x] Reconcile Yaad's implemented, experimental, and planned interface docs. - Evidence: yaad TUI split to `cmd/yaad-tui` nested module; core library has no - Bubble Tea deps (2026-07-11). - -Acceptance: boundary checks and repository documentation agree with actual -imports and implemented interfaces; all repository test suites pass. - -## Verification pass 1 - -- [x] Hawk focused tests (memory, cloud client, cmd) after charm/yaad work -- [x] Yaad full `go test ./...` + nested `cmd/yaad-tui` tests -- [x] Hawk Cloud vitest results present (`metering`, `openapi-parity`, - `authorization-matrix`, …) -- [ ] Full matrix across all fourteen repos (optional CI babysit) - -## Verification pass 2 - -- [ ] Repeat builds/tests with clean workspace-local caches -- [ ] Repeat Hawk with `GOWORK=off` after yaad is published -- [ ] Re-run submodule/release parity after engine pushes -- [x] Audit checkboxes against command or source evidence (this pass) - -## Still open (prioritized) - -1. **Publish engines then re-pin** — push `yaad` (and any other local-only - engine SHAs), refresh hawk `go.sum`, green `submodule-release-parity`. -2. **OpenAPI breaking-change CI** — add oasdiff (or equivalent) on - `hawk/api/openapi.yaml` and `hawk-cloud/contracts/openapi.yaml`. -3. **GrayCode BFF domain split** — split large organization route modules by - domain for maintainability (behavior already contract-tested). diff --git a/docs/plans/hawk-contracts-migration-backlog.md b/docs/plans/hawk-contracts-migration-backlog.md index 70fbb5b2..fe4e0aa8 100644 --- a/docs/plans/hawk-contracts-migration-backlog.md +++ b/docs/plans/hawk-contracts-migration-backlog.md @@ -8,7 +8,6 @@ External follow-up still outside the scope of this local workspace audit: - confirm upstream branches contain the final architecture commits - confirm published module tags/releases match the merged contract changes -- execute `architecture-upstream-release-plan.md` ## Done diff --git a/docs/plans/z-ai-proper-implementation.md b/docs/plans/z-ai-proper-implementation.md deleted file mode 100644 index 8ba7d1ba..00000000 --- a/docs/plans/z-ai-proper-implementation.md +++ /dev/null @@ -1,337 +0,0 @@ -# Z.AI Proper Gateway Implementation Plan - -**Status:** Plan (ready for implementation) -**Date:** 2026 (current) -**Owners:** Hawk + Eyrie teams (cross-repo via go.work) -**Related:** Xiaomi MiMo per-plan/region split (the direct precedent) -**Goal:** First-class support for Z.AI (Zhipu/GLM) **Coding Plan** (subscription/quota, dedicated endpoint) alongside general **pay-as-you-go** API, with **region awareness** (global vs CN), matching the maturity, dynamism, reuse, reliability, and UX of the Xiaomi implementation while preserving the "live when configured + registry-driven" architecture. - ---- - -## 1. Executive Summary - -Current Z.AI support is a single generic live-only OpenAI-compat gateway (`z-ai` / `z-ai-direct`, `ZAI_API_KEY`, default `https://api.z.ai/api/paas/v4`). This is insufficient. - -Z.AI reality (confirmed against official quick-start and tooling usage): -- **GLM Coding Plan**: Subscription-based (Lite/Pro/Max tiers, prompt/quota model with 5-hour rolling windows + MCP quotas). Marketed for Cursor, Claude Code, Cline, etc. **Must** use the dedicated coding endpoint for correct billing/quota consumption and plan-eligible models. -- **General API (pay-as-you-go)**: Standard token billing on the general endpoint. -- **Endpoints** (from Z.AI developer docs): - - General: `https://api.z.ai/api/paas/v4` (or CN equivalent) - - Coding Plan: `https://api.z.ai/api/coding/paas/v4` -- **Regions**: `api.z.ai` (global/international branding, primary for Coding Plan docs) vs China platform (`open.bigmodel.cn` / bigmodel.cn family). Affects billing, quotas, latency, and model availability. CN equivalents of the coding path exist or are expected. -- Reference catalog currently lists only minimal `z-ai/glm-4.5-air:free`; real breadth (GLM-4.5/4.7/5/Flash/V variants, vision/tooling) comes via live `/models` on the correct base. - -The architecture (ProviderSpec + live fetchers + decorator clients + Hawk gateway surface) is already excellent: dynamic (new gateway = spec + fetcher + data), heavily reused (OpenAI client + compat flags + ProtocolRouter patterns), reliable (retriable-only failover, negative caching, probes), secure (centralized CredentialEnv, no secrets in JSON), and fast (compiled catalog, on-demand counts). - -**The gap is only specialization surface for Z.AI**, exactly analogous to the pre-split state of Xiaomi MiMo (which received dedicated `xiaomi_mimo_token_plan` + `payg`, region picker, `catalog/xiaomi/`, dual-protocol client, Hawk UI, config resolution, and detailed docs). - -This plan adds **one new setup gateway** (`z_ai_coding`) while keeping the existing `z-ai` (general) fully backward-compatible. Total setup gateways become 19. No breaking changes for existing users. - ---- - -## 2. Current State (Precise Inventory) - -### Eyrie (external/eyrie) -- `catalog/registry/providers.go:68` (single entry): - ```go - { - ProviderID: "z-ai", DisplayName: "Z.AI", DeploymentID: "z-ai-direct", SortOrder: 7, - RequiresKey: true, CredentialEnv: "ZAI_API_KEY", - BaseURLEnv: []string{"ZAI_BASE_URL", "ZAI_API_BASE", "OPENAI_BASE_URL", "OPENAI_API_BASE"}, - ProbeKind: ProbeOpenAIModels, ProbeBaseURL: "https://api.z.ai/api/paas/v4", - LiveFetcherKey: "z-ai", LiveCatalogKey: "z-ai", - APIProtocolID: "openai-chat-completions", AdapterID: "z-ai", - }, - ``` -- `catalog/live/fetchers.go:26,50,729`: - - `DefaultZAIBaseURL = "https://api.z.ai/api/paas/v4"` - - Registry: `"z-ai": FetchZAI` - - `FetchZAI`: `fetchOpenAICompatModels(..., envOr(..., "ZAI_BASE_URL", DefaultZAIBaseURL), "ZAI_API_KEY", "Bearer")` + `enrichFromOpenRouter(entries, "z-ai/")` -- `setup/deployment.go:223`: - - `"z-ai-direct"` → `client.NewOpenAIClient(..., &client.ZAICompat)` -- `client/compat.go:43`: - - `ZAICompat = OpenAICompatConfig{ ThinkingFormat: "zai", MaxTokensField: "max_tokens", SupportsUsageInStreaming: true }` -- `config/providers.go:27`, `config/profiles.go`, `config/provider_env.go`, `config/runtime.go`, etc.: `ProviderZAI`, `ZAIRuntimeProfile`, `DefaultZAIOpenAIBaseURL`, env collection for `ZAI_API_KEY` / `ZAI_BASE_URL*`. -- `catalog/live/zai_test.go` exists (thin coverage noted in docs). -- No `catalog/zai/` subpackage (unlike `catalog/xiaomi/`). - -### Hawk -- `internal/config/catalog_api.go`: - - `AllSetupGateways()` pulls from `registry.CredentialRegistry()` (dynamic). - - `setupGatewayRegistryID` switch already has `case "zai": return "z-ai"` (plus xiaomi special cases, google→gemini, xai→grok). - - `GatewayDisplayName`, `IsSetupGateway`, `GatewayForModel`, `ActiveGateway` all go through the normalizer. -- `cmd/chat_config_gateways.go`: Special-case only for `ProviderXiaomiTokenPlan` (region flow before key paste, hints in footer). -- No `chat_config_zai.go` or `internal/config/zai_setup.go`. -- `internal/config/catalog_gateways_test.go:14`: Hard `len(gws) != 18` + explicit want list (includes the two xiaomi + two minimax). -- `internal/config/xiaomi_setup.go` + `cmd/chat_config_xiaomi.go` + `xiaomi_setup_test.go`: The full Hawk-side pattern for region-aware plan gateways. -- `internal/config/eyrie_apply.go` and `credentials_store.go`: Xiaomi-specific Apply/region env injection. - -### Docs (stale in places) -- `external/eyrie/docs/guides/CREDENTIAL-SETUP-FLOW.md`: Lists 12 gateways (stale), has a full "Xiaomi MiMo (two gateways...)" subsection with tables for keys/bases/paths. Z.AI is one line: "live /models only". -- `external/eyrie/docs/guides/DYNAMIC-MODEL-DISCOVERY.md`: Notes "thin test coverage (z-ai...)", "All 12 setup gateways", Z.AI row describes only generic OpenAI-compat. -- Hawk `docs/DYNAMIC-MODELS.md` and others reference the gateway surface generically. -- Reference catalog (langdag) has minimal data for z-ai. - -### Architecture Strengths (no changes needed) -- Everything funnels through ProviderSpec + live fetch + `runtime.ListModels(Source: auto)`. -- Decorators (Weighted/Fallback/RateLimit/Tracing/ProtocolRouter) are provider-agnostic. -- Credential centralization + guardian in Hawk front everything. -- `go work sync` + submodule hygiene enforced in CI. - ---- - -## 3. Xiaomi Precedent (Copy This Pattern) - -Xiaomi split was the first "billing plan + region + special hosts" case. - -**Eyrie additions:** -- Two `ProviderSpec` rows with distinct `ProviderID`, `DisplayName`, `CredentialEnv`, `BaseURLEnv`, `LiveFetcherKey`, `LiveCatalogKey`, `DeploymentID`, `ProbeBaseURL` (empty for token plan because resolved). -- New package `catalog/xiaomi/`: - - `endpoints.go`: `Billing`/`Region` types + constants for every host (payg + 3 token-plan regions × OpenAI + Anthropic), `NormalizeRegion`, `BillingForProvider`, `ResolveOpenAIBase`/`ResolveAnthropicBase` (override wins, region required for token plan), key-shape mismatch hints (`tp-` vs `sk-`). - - `platform.go` + `http.go`: Separate platform catalog fetch for rich metadata (context/pricing/names) because inference `/v1/models` is sparse. `ApplyPlatformMetadata`. -- `client/mimo.go`: `NewMiMoClient` (dual OpenAI + Anthropic bases, compat, retriable failover via existing machinery). -- `config/xiaomi_profile.go`: Env consts (`EnvXiaomi*`), `ResolveXiaomiOpenAIBase`/`ResolveXiaomiAnthropicBase` (load provider.json + delegate to catalog/xiaomi), `IsXiaomiMimoProvider`, legacy migration. -- `setup/deployment.go`: `newMiMoDeploymentClient` that resolves bases via config + xiaomi package before `NewMiMoClient`. -- Registry live fetchers: `FetchXiaomiPayg` + `FetchXiaomiTokenPlan` (registered under the two keys). - -**Hawk additions (thin UI + bridge only):** -- `internal/config/xiaomi_setup.go`: `ProviderXiaomiTokenPlan` const, `NeedsXiaomiTokenPlanRegion`, `SetXiaomiTokenPlanRegion` (persist + set envs for probe + derive base), `XiaomiTokenPlanRegionLabel`, `ApplyXiaomiTokenPlanRegionEnv`. -- `cmd/chat_config_xiaomi.go`: Region list (cn/sgp/ams), picker view, key handler that calls Set + invalidates cache + routes to key paste or post-save flow. Special hints. -- `cmd/chat_config_gateways.go`: In `handleConfigGatewaysSelect` and hint rendering: if the row is the token-plan gateway and needs region (or no key), launch region flow first. -- Tests + `catalog_gateways_test.go` updates. -- `eyrie_apply.go` etc. call the Apply*Env hook. - -**Result:** Users see two distinct rows in /config, get region prompt only for token plan, correct hosts are used for probe/fetch/chat, key mismatch hints, rich models, full docs. - -Z.AI needs the same treatment (plan split + region), but likely simpler client side (no Anthropic dual path documented yet; both paths are OpenAI-compat with the existing "zai" thinking format). - ---- - -## 4. Proposed Design - -### 4.1 Registry Entries (external/eyrie/catalog/registry/providers.go) -Add after the existing z-ai (keep the original as general payg for backward compat + users who intentionally use general API): - -```go -{ - ProviderID: "z-ai", DisplayName: "Z.AI", DeploymentID: "z-ai-direct", SortOrder: 7, - // ... (unchanged, general /paas/v4) -}, -{ - ProviderID: "z_ai_coding", DisplayName: "Z.AI — Coding Plan", DeploymentID: "z_ai_coding-direct", SortOrder: 7, // or 19 after re-sort - RequiresKey: true, CredentialEnv: "ZAI_CODING_API_KEY", - BaseURLEnv: []string{"ZAI_CODING_BASE_URL", "ZAI_BASE_URL", "OPENAI_BASE_URL", "OPENAI_API_BASE"}, - ProbeKind: ProbeOpenAIModels, ProbeBaseURL: "https://api.z.ai/api/coding/paas/v4", - LiveFetcherKey: "z_ai_coding", LiveCatalogKey: "z_ai_coding", - APIProtocolID: "openai-chat-completions", AdapterID: "z-ai", -}, -``` - -(Alternative naming: `z_ai_coding_plan` to match `xiaomi_mimo_token_plan` verbosity. `z_ai_coding` is shorter and clear in TUI. Choose one; document alias handling.) - -Add `case "z_ai_coding", "zai-coding", "z-ai_coding": return "z_ai_coding"` in Hawk's `setupGatewayRegistryID`. - -### 4.2 New Eyrie Package: catalog/zai/ (modeled exactly on catalog/xiaomi/) -- `endpoints.go`: - - Types: `Plan` ("general" | "coding"), `Region` ("global" | "cn" or more specific if needed). - - Constants for bases: - - General global: `https://api.z.ai/api/paas/v4` - - Coding global: `https://api.z.ai/api/coding/paas/v4` - - CN variants (research + docs): `https://open.bigmodel.cn/api/paas/v4`, `https://open.bigmodel.cn/api/coding/paas/v4` (or the actual CN coding host; confirm at implementation time). - - `NormalizeRegion`, `PlanForProvider`, `ResolveOpenAIBase(plan, region, override string)`. - - Optional: key hinting if dashboard produces distinguishable prefixes for coding keys. -- `platform.go` or enrichment (optional; start with OpenRouter "z-ai/" enrichment which FetchZAI already does; add dedicated if Z.AI coding catalog differs significantly). -- Tests: `endpoints_test.go` (table-driven, like xiaomi). - -### 4.3 Live Fetchers (catalog/live/fetchers.go) -- Keep `FetchZAI` for the `z-ai` key (general). -- Add: - ```go - "z_ai_coding": FetchZAICoding, - ``` -- Implement `FetchZAICoding` (or a single `FetchZAIWithPlan`): - - Resolve base via new `config.ResolveZAIOpenAIBase("z_ai_coding", cfg)` (or env first). - - Call `fetchOpenAICompatModels(..., resolvedBase, key, "Bearer")`. - - Same OpenRouter enrichment (or "z_ai_coding/" if they publish distinct). -- Export `DefaultZAICodingBaseURL` etc. in `config/providers.go`. - -Update Registry map and any `fetchers_test` / `live_test`. - -### 4.4 Client + Deployment + Config (minimal) -- `setup/deployment.go`: Add case `"z_ai_coding-direct":` → resolve base (via new config helper + LoadProviderConfig) then `NewOpenAIClient(apiKey, resolved, &client.ZAICompat)`. Reuse the same compat (thinking "zai" format applies). -- `config/providers.go`: Add `DefaultZAICodingOpenAIBaseURL`. -- `config/xai_profile.go` or new `config/zai_profile.go` (or extend existing ZAI bits): - - Env consts: `EnvZAICodingAPIKey`, `EnvZAICodingBaseURL`, `EnvZAICodingRegion` (or plan-specific). - - `ResolveZAIOpenAIBase(providerID string, cfg *ProviderConfig)`. - - Migration for any legacy. -- `profiles.go` / `provider_env.go` / `runtime.go`: Wire the new provider ID into profiles, env collection, and `ZAICodingRuntimeProfile` if distinct mode needed (likely same "openai" mode). -- No new client file needed initially (reuse OpenAI path + ZAICompat). If future dual-protocol or coding-specific headers appear, add `NewZAIClient` parallel to MiMo. - -### 4.5 Hawk Surface (UI + Bridge) -- `internal/config/zai_setup.go` (new, modeled 1:1 on `xiaomi_setup.go`): - ```go - const ProviderZAICoding = "z_ai_coding" - - func NeedsZAIRegionOrPlan(providerID string) bool { ... } - func SetZAIRegion(...) error { ... } - func ZAIRegionLabel() string { ... } - func ApplyZAIRegionEnv(ctx context.Context) { ... } // sets process envs before probe - ``` - Delegate to `eyriecfg` (new Resolve helpers) + `catalog/zai`. -- `cmd/chat_config_zai.go` (new): - - Region/plan options (e.g. "Global (Coding)", "China (Coding)", "Global (General)" — or separate flows). - - View + key handler. Special footer hints: "Coding Plan keys from z.ai dashboard · uses /coding/paas/v4". -- `cmd/chat_config_gateways.go`: - - In select + hints: if row.ID == hawkconfig.ProviderZAICoding && needs region/plan → launch zai flow (like Xiaomi). - - Update any hardcoded Xiaomi-only hints to a helper or switch. -- Update `catalog_gateways_test.go`: change `18` → `19`, add "z_ai_coding" to want list or remove brittle explicit map. -- `eyrie_apply.go`, startup, cache invalidation: call the new Apply hook for the coding provider. -- `catalog_api.go`: add alias cases in `setupGatewayRegistryID` (keep the switch small; long-term consider adding `Aliases []string` to ProviderSpec + derive logic in eyrie registry to kill the switch). - -### 4.6 Other Surfaces -- Credentials migrate/alias: `credentials/store.go` etc. for `zai_coding_api_key` → `ZAI_CODING_API_KEY`. -- Runtime profiles and deployment env sync. -- Any conformance or verify tests that enumerate providers. - ---- - -## 5. Implementation Phases (Actionable, File-by-File) - -### Phase 0 — Foundations (Eyrie, no UX yet) -1. Add the second `ProviderSpec` row in `external/eyrie/catalog/registry/providers.go`. -2. Add consts + `ResolveZAIOpenAIBase` (and region/plan types) in a new `external/eyrie/catalog/zai/endpoints.go` (copy structure from xiaomi/endpoints.go; include CN bases once confirmed). -3. Update `external/eyrie/catalog/live/fetchers.go`: - - New default const. - - New fetcher func + registration `"z_ai_coding": FetchZAICoding`. - - (FetchZAI stays for the general key.) -4. `external/eyrie/config/providers.go`: new `DefaultZAICodingOpenAIBaseURL`. -5. `external/eyrie/setup/deployment.go`: add case for `z_ai_coding-direct` (resolve base first). -6. Wire minimal profile/env bits (can live in existing ZAI sections or small new `zai_profile.go` modeled on `xiaomi_profile.go`). -7. Update `external/eyrie/catalog/live/zai_test.go` (or add `zai_coding_test.go`) + any live parity tests. -8. `go test -race ./external/eyrie/catalog/...` (and full package). - -**Deliverable:** `z_ai_coding` appears in `registry.All()` and can be resolved; live fetch works when `ZAI_CODING_API_KEY` + correct base is set. - -### Phase 1 — Eyrie Config + Runtime Polish -- Full resolution + provider.json storage for region/plan (parallel to `XiaomiMimo*` fields). -- Legacy migration if anyone had custom ZAI_BASE_URL pointing at coding before. -- Ensure `runtime.ListModels` + discover use the right fetcher key per deployment. -- Update any default model / catalog bootstrap for the new provider ID. - -### Phase 2 — Hawk UI + Config Bridge -1. Create `internal/config/zai_setup.go` + `_test.go` (table-driven; use `credentials.MapStore`). -2. Create `cmd/chat_config_zai.go` + `_test.go` (region/plan picker modeled exactly on xiaomi; include "g" hotkey support for "change region/plan"). -3. Edit `cmd/chat_config_gateways.go`: - - Import and use the new const. - - Add conditionals for the coding provider ID in select/hints (extract a small helper if the if-chain grows). -4. Edit `internal/config/catalog_api.go` (add cases to the switch for aliases). -5. Edit `internal/config/eyrie_apply.go`, `catalog_startup.go`, ui caches etc. to call Apply hook for coding provider. -6. Update `internal/config/catalog_gateways_test.go` (19 gateways, "z_ai_coding" present). -7. `go test -race ./internal/config/... ./cmd/... -run 'Gateway|ZAI|Config'`. - -### Phase 3 — Tests & Hardening -- Table-driven tests for resolution, fetch (with env overrides), region normalize. -- Integration-style via `scripts/test-config-flow.sh` or new zai flow test. -- Update hawk `catalog_startup_test.go`, `ui_cache_test` etc. that range over `AllSetupGateways()`. -- Run full `go test -race -count=1 ./...`. -- `make smoke`, `make ci` (local). - -### Phase 4 — Documentation (required for "proper") -- `external/eyrie/docs/guides/CREDENTIAL-SETUP-FLOW.md`: - - Fix header count. - - Add full subsection for Z.AI parallel to Xiaomi (tables for general vs coding, global vs CN bases, key source, "Coding Plan keys from z.ai dashboard after subscribe", note that Coding Plan is intended for supported coding tools). - - Official links (from research): Z.AI quick-start, devpack, platform dashboard. -- `external/eyrie/docs/guides/DYNAMIC-MODEL-DISCOVERY.md`: update "12" → "19", remove "thin coverage (z-ai)" note, add Z.AI row with plan/region details. -- Hawk `docs/DYNAMIC-MODELS.md` and `docs/ECOSYSTEM-CONFIG.md` if they enumerate. -- `external/eyrie/CHANGELOG.md` + Hawk `CHANGELOG.md` entries (conventional). -- Optional: contribute richer z-ai entries (including coding variants) to the reference catalog JSON. - -### Phase 5 — Git / PR Hygiene (AGENTS.md) -- Work on feature branch only: `git checkout -b feat/z_ai_coding-plan-support`. -- Conventional commits (no co-author trailers — lefthook + history rules). -- `go fmt` / `go vet` / `golangci-lint` clean locally. -- Full `-race` + `make smoke` + `make ci` (or background) must be green before PR. -- `gh pr create --fill` (or with description referencing this plan). -- Address any required 8 status checks. -- After approval/CI: `gh pr merge --squash --delete-branch` (or admin if needed). -- Post-merge: verify `origin/main` clean, no lingering feature branches, `go work sync` clean, submodules updated, only main remote. -- (If history issues ever arise again: follow prior filter-branch + gh api protected-branch relax pattern, but avoid.) - ---- - -## 6. Backward Compatibility & Migration -- Existing `z-ai` + `ZAI_API_KEY` + `ZAI_BASE_URL` (or env fallbacks) continue to target the general endpoint exactly as today. No change in behavior. -- Users with Coding Plan subscriptions will see a new row "Z.AI — Coding Plan" in the Gateways tab. They paste the plan key (separate env `ZAI_CODING_API_KEY` recommended so both can coexist). -- Old custom `ZAI_BASE_URL` pointing at coding path will still work for the general row (override wins); the new coding row will prefer its own env + resolved value. -- Provider.json fields for region/plan are additive. -- Live discovery for the new gateway ID works immediately after key save (same as Xiaomi). -- No impact on non-setup providers or aggregators. - ---- - -## 7. Open Questions / Risks (Resolve During Implementation) -- Exact CN coding base URL? (Confirm on official CN docs / dashboard at implementation time; default to documented patterns.) -- Do Coding Plan keys have a distinguishable prefix (like Xiaomi `tp-`)? If yes, add `KeyMismatchHint` + append on probe errors. -- Does the coding endpoint return meaningfully different model metadata (pricing is quota-based, not token)? Fetcher may need light post-processing or skip certain enrichment. -- Is an Anthropic-compat path published for the coding plan (unlikely per current docs; if added later, extend like MiMo). -- Should we allow the same key env for both rows (with warning) or enforce distinct like Xiaomi? Distinct is cleaner for quota tracking. -- Reference catalog updates (optional follow-up). -- SortOrder: keep z-ai at 7; place coding immediately after or give it its own logical order. - ---- - -## 8. Verification Checklist (Before PR + On Main) -- [ ] `AllSetupGateways()` returns 19 items including both z-ai variants; test passes. -- [ ] `/config` shows two distinct Z.AI rows with correct display names. -- [ ] Selecting Coding Plan (no region/plan set) triggers picker → persist → key paste flow. -- [ ] Probe + live list + chat all use `/coding/paas/v4` (or CN) when the coding gateway + region chosen. -- [ ] General `z-ai` row unaffected. -- [ ] `ZAI_CODING_API_KEY` and `ZAI_API_KEY` can both be stored. -- [ ] Region change ("g" or re-select) updates provider.json + derives correct base for probe/fetch. -- [ ] Full `go test -race -count=1 ./...` green. -- [ ] `make smoke` and local `make ci` (lint/vet/module hygiene) clean. -- [ ] Docs updated + table counts match reality. -- [ ] gh PR flow followed; 8 checks green on the PR; merged to main via gh; branches cleaned; main + origin in sync; no co-authors in new commits. - ---- - -## 9. Appendix — Copy-Paste Starting Points - -**Hawk bridge (internal/config/zai_setup.go skeleton):** -```go -package config - -import ( - "context" - "os" - "strings" - - eyriecfg "github.com/GrayCodeAI/eyrie/config" - "github.com/GrayCodeAI/eyrie/catalog/zai" -) - -const ProviderZAICoding = "z_ai_coding" - -func NeedsZAIRegionOrPlan(providerID string) bool { /* similar to Xiaomi */ } -func SetZAIRegionOrPlan(...) error { /* persist to provider.json via eyriecfg, set envs, derive base */ } -func ApplyZAIRegionEnv(ctx context.Context) { /* ... */ } -``` - -**Eyrie endpoints (external/eyrie/catalog/zai/endpoints.go):** -Copy the structure of `xiaomi/endpoints.go` (Billing/Region → Plan/Region, all the Resolve* funcs, const bases for coding/general × global/cn). - -**Gateway select special case (cmd/chat_config_gateways.go):** -Add parallel to the existing XiaomiTokenPlan block (search for `ProviderXiaomiTokenPlan`). - -**Test count bump:** -Only the one `len(gws) != 18` assertion + the want map in `internal/config/catalog_gateways_test.go`. - ---- - -**End of Plan** - -This document is the single source for the implementation. After writing code, update this file with "Implemented" status + links to the merged PR(s). - -Follow AGENTS.md at every step: tests beside source, table-driven where multi-case, conventional signed commits, feature branch + gh PR only, full `-race` + make ci green, no direct main, ecosystem (go.work + external/eyrie) hygiene. - -When ready to execute: create the feature branch and begin Phase 0 in eyrie (the registry + fetcher + catalog/zai package changes are the highest-leverage first commits). diff --git a/internal/testaudit/docs_audit_test.go b/internal/testaudit/docs_audit_test.go index 28d81c92..df1488d7 100644 --- a/internal/testaudit/docs_audit_test.go +++ b/internal/testaudit/docs_audit_test.go @@ -16,7 +16,6 @@ func TestArchitectureDocsDoNotContainStaleContractsLanguage(t *testing.T) { "docs/architecture/README.md", "docs/architecture/hawk-product-architecture.md", "docs/architecture/hawk-core-contracts-spec.md", - "docs/architecture/hawk-contract-migration-inventory.md", "docs/plans/hawk-contracts-migration-backlog.md", } diff --git a/plans/THEMING-ENHANCEMENT-PLAN.md b/plans/THEMING-ENHANCEMENT-PLAN.md deleted file mode 100644 index a53deade..00000000 --- a/plans/THEMING-ENHANCEMENT-PLAN.md +++ /dev/null @@ -1,154 +0,0 @@ -# Theming Enhancement Plan - -**Goal:** Complete theming parity with Grok, adding auto-detection, customization options, and polish. - -## Current State - -Hawk already has: -- ✅ 17 built-in themes (dark, dracula, nord, gruvbox, tokyo-night, catppuccin, one-dark, solarized-dark, rose-pine, everforest, monokai, kanagawa, ayu, palenight, github-dark, light, solarized-light) -- ✅ Theme picker UI -- ✅ `/theme` slash command -- ✅ Settings persistence - -Missing features: -- ✅ Auto-detect OS dark/light appearance (implemented) -- ✅ Color quantization for 256-color/16-color terminals (implemented) -- ✅ Scroll customization (speed, invert) (implemented) -- ✅ Compact mode toggle (implemented) -- ✅ Theme preview in picker (implemented) - ---- - -## Implementation Plan - -### Phase 1: Auto Theme Detection (Done) - -**Add `/hawk/internal/theme/auto_detect.go`:** -- ✅ Detect macOS AppleInterfaceStyle -- ✅ Detect Windows AppsUseLightTheme -- ✅ Linux XDG fallback via GTK_THEME - -**Add to theme picker (`theme_picker.go`):** -- ✅ Add "auto" option to registry - -**Settings:** -```json -{ - "theme": "auto" -} -``` - -### Phase 2: Color Quantization (Done) - -**Add `/hawk/internal/theme/quantize.go`:** -- ✅ DetectColorLevel (basic/256/truecolor) -- ✅ HexToRGB conversion -- ✅ RGBTo256 mapping -- ✅ RGBToANSI mapping -- ✅ QuantizePalette function - -### Phase 3: Scroll Customization (Done) - -**Implemented in `internal/config/settings.go` and `cmd/chat_subcommand_simple.go`:** -- ✅ `/scroll-speed <1-100>` command -- ✅ `/scroll-invert` toggle command -- ✅ Settings fields: `scroll_speed`, `invert_scroll` - -### Phase 4: Compact Mode (Done) - -**Implemented in `internal/config/settings.go` and `cmd/chat_subcommand_simple.go`:** -- ✅ `/compact-mode` toggle command -- ✅ Settings field: `compact_mode` - -### Phase 5: Theme Preview (Done) - -**Implemented in `cmd/theme_picker.go`:** -- ✅ Live preview shown when navigating themes -- ✅ Visual swatches for panel, prompt, accent, text, green, red colors - ---- - -### Phase 6: Additional Commands (Done) - -**Implemented in `cmd/chat_subcommand_simple.go` and `internal/tool/prompt_queue.go`:** -- ✅ `/prompt-queue` command with add/list/clear/remove subcommands -- ✅ `/scroll-mode` command with auto/wheel/trackpad options -- ✅ `/terminal-setup` command showing configuration recommendations -- ✅ `/pager-config` command for scrollback buffer and line numbers - -**Added to `internal/theme/theme.go`:** -- ✅ PagerConfig struct with BufferLines, Margins, ShowLineNumbers fields -- ✅ PageMargins struct for layout spacing - -**Added to `internal/config/settings.go`:** -- ✅ PaginatorLines setting -- ✅ PaginatorShowLineNums setting -- ✅ PaginatorMarginTop/Bottom settings - ---- - -## Detailed Tasks - -| Task | File | Effort | -|------|------|--------| -| Auto theme detection | `internal/theme/auto_detect.go` | 1 day | -| XDG portal support | `internal/theme/xdg.go` | 1 day | -| Color quantization | `internal/theme/quantize.go` | 2 days | -| Scroll config struct | `internal/theme/theme.go` | 0.5 day | -| Scroll slash commands | `cmd/chat_subcommand_simple.go` | 0.5 day | -| Compact mode toggle | `cmd/chat_subcommand_simple.go`, `internal/theme/theme.go` | 0.5 day | -| Theme preview in picker | `cmd/theme_picker.go` | 1 day | -| Terminal capability detection | `internal/theme/capabilities.go` | 1 day | -| Update user-guide docs | `docs/user-guide/06-theming.md` | 0.5 day | - ---- - -## Settings Schema - -```json -{ - "theme": "auto", - "ui": { - "scroll_speed": 50, - "scroll_mode": "auto", - "invert_scroll": false, - "compact_mode": false, - "vim_mode": false - } -} -``` - ---- - -## Environment Variables - -| Variable | Description | -|----------|-------------| -| `HAWK_THEME` | Override theme selection | -| `HAWK_SCROLL_SPEED` | Override scroll speed | -| `HAWK_INVERT_SCROLL` | Enable natural scrolling | - ---- - -## Testing Matrix - -| Terminal | Auto Theme | Quantization | Notes | -|----------|------------|--------------|-------| -| iTerm2 | ✅ | ✅ | Full support | -| Terminal.app | ✅ | ✅ | 256-color max | -| VS Code terminal | ✅ | ✅ | xterm.js | -| tmux | ✅ | ✅ | Requires config | -| SSH | ⚠️ | ✅ | Auto theme needs OSC 11 fallback | - ---- - -## Milestones - -1. **Week 1:** Auto theme detection working on all platforms -2. **Week 2:** Color quantization and terminal detection -3. **Week 3:** Scroll customization and compact mode -4. **Week 4:** Polish and documentation - ---- - -© 2026 GrayCode AI. All rights reserved. \ No newline at end of file From 5b328085e7e12286d971a3f7c4f588834ca7b305 Mon Sep 17 00:00:00 2001 From: Lakshman Patel Date: Wed, 5 Aug 2026 07:29:38 +0530 Subject: [PATCH 2/3] chore(spec): drop dead vendored skill/spec-kit docs --- docs/architecture/spec.md | 2 +- spec/README.md | 130 +- spec/agent-skills/AGENTS.md | 90 -- spec/agent-skills/CLAUDE.md | 56 - spec/agent-skills/agents/code-reviewer.md | 97 -- spec/agent-skills/agents/security-auditor.md | 112 -- spec/agent-skills/agents/test-engineer.md | 95 -- .../agents/web-performance-auditor.md | 184 --- spec/agent-skills/commands/build.toml | 43 - spec/agent-skills/commands/code-simplify.toml | 22 - spec/agent-skills/commands/planning.toml | 16 - spec/agent-skills/commands/review.toml | 16 - spec/agent-skills/commands/ship.toml | 72 - spec/agent-skills/commands/spec.md | 15 - spec/agent-skills/commands/spec.toml | 15 - spec/agent-skills/commands/test.toml | 19 - spec/agent-skills/commands/webperf.toml | 32 - spec/agent-skills/definition-of-done.md | 67 - spec/agent-skills/docs/agents.md | 123 -- spec/agent-skills/docs/antigravity-setup.md | 123 -- spec/agent-skills/docs/comparison.md | 82 -- spec/agent-skills/docs/copilot-setup.md | 87 -- spec/agent-skills/docs/cursor-setup.md | 58 - spec/agent-skills/docs/gemini-cli-setup.md | 132 -- spec/agent-skills/docs/getting-started.md | 152 --- spec/agent-skills/docs/opencode-setup.md | 178 --- spec/agent-skills/docs/skill-anatomy.md | 170 --- spec/agent-skills/docs/windsurf-setup.md | 48 - spec/agent-skills/hooks/SDD-CACHE.md | 167 --- spec/agent-skills/hooks/SIMPLIFY-IGNORE.md | 90 -- spec/agent-skills/hooks/hooks.json | 14 - spec/agent-skills/hooks/sdd-cache-post.sh | 135 -- spec/agent-skills/hooks/sdd-cache-pre.sh | 106 -- spec/agent-skills/hooks/session-start-test.sh | 46 - spec/agent-skills/hooks/session-start.sh | 24 - .../hooks/simplify-ignore-test.sh | 247 ---- spec/agent-skills/hooks/simplify-ignore.sh | 302 ----- .../references/accessibility-checklist.md | 160 --- .../references/definition-of-done.md | 67 - .../references/observability-checklist.md | 91 -- .../references/orchestration-patterns.md | 370 ------ .../references/performance-checklist.md | 153 --- .../references/security-checklist.md | 179 --- .../references/testing-patterns.md | 236 ---- .../skills/api-and-interface-design/SKILL.md | 294 ----- .../browser-testing-with-devtools/SKILL.md | 317 ----- .../skills/ci-cd-and-automation/SKILL.md | 390 ------ .../skills/code-review-and-quality/SKILL.md | 381 ------ .../skills/code-simplification/SKILL.md | 331 ----- .../skills/context-engineering/SKILL.md | 289 ---- .../debugging-and-error-recovery/SKILL.md | 300 ----- .../skills/deprecation-and-migration/SKILL.md | 206 --- .../skills/documentation-and-adrs/SKILL.md | 278 ---- .../skills/doubt-driven-development/SKILL.md | 243 ---- .../skills/frontend-ui-engineering/SKILL.md | 328 ----- .../git-workflow-and-versioning/SKILL.md | 355 ----- spec/agent-skills/skills/idea-refine/SKILL.md | 178 --- .../skills/idea-refine/examples.md | 239 ---- .../skills/idea-refine/frameworks.md | 99 -- .../skills/idea-refine/refinement-criteria.md | 113 -- .../skills/idea-refine/scripts/idea-refine.sh | 15 - .../incremental-implementation/SKILL.md | 249 ---- .../agent-skills/skills/interview-me/SKILL.md | 225 ---- .../SKILL.md | 203 --- .../skills/performance-optimization/SKILL.md | 349 ----- .../planning-and-task-breakdown/SKILL.md | 234 ---- .../skills/security-and-hardening/SKILL.md | 461 ------- .../skills/shipping-and-launch/SKILL.md | 310 ----- .../skills/source-driven-development/SKILL.md | 194 --- .../skills/spec-driven-development/SKILL.md | 206 --- .../skills/test-driven-development/SKILL.md | 383 ------ .../skills/using-agent-skills/SKILL.md | 191 --- spec/agent-skills/spec-driven-development.md | 206 --- spec/openspec/docs/README.md | 114 -- spec/openspec/docs/agent-contract.md | 137 -- spec/openspec/docs/cli.md | 1170 ----------------- spec/openspec/docs/commands.md | 707 ---------- spec/openspec/docs/concepts.md | 628 --------- spec/openspec/docs/customization.md | 356 ----- spec/openspec/docs/editing-changes.md | 91 -- spec/openspec/docs/examples.md | 215 --- spec/openspec/docs/existing-projects.md | 134 -- spec/openspec/docs/explore.md | 121 -- spec/openspec/docs/faq.md | 155 --- spec/openspec/docs/getting-started.md | 289 ---- spec/openspec/docs/glossary.md | 91 -- spec/openspec/docs/how-commands-work.md | 159 --- spec/openspec/docs/installation.md | 115 -- spec/openspec/docs/migration-guide.md | 596 --------- spec/openspec/docs/multi-language.md | 115 -- spec/openspec/docs/opsx.md | 659 ---------- spec/openspec/docs/overview.md | 91 -- spec/openspec/docs/reviewing-changes.md | 143 -- spec/openspec/docs/supported-tools.md | 112 -- spec/openspec/docs/team-workflow.md | 74 -- spec/openspec/docs/troubleshooting.md | 166 --- spec/openspec/docs/workflows.md | 482 ------- spec/openspec/docs/writing-specs.md | 101 -- .../add-global-install-scope/design.md | 161 --- .../add-global-install-scope/proposal.md | 101 -- .../specs/ai-tool-paths/spec.md | 35 - .../specs/cli-config/spec.md | 21 - .../specs/cli-init/spec.md | 28 - .../specs/cli-update/spec.md | 34 - .../specs/command-generation/spec.md | 22 - .../specs/global-config/spec.md | 24 - .../specs/installation-scope/spec.md | 71 - .../add-global-install-scope/tasks.md | 61 - .../examples/add-qa-smoke-harness/proposal.md | 45 - .../specs/developer-qa-workflow/spec.md | 49 - .../proposal.md | 111 -- .../specs/cli-init/spec.md | 121 -- .../specs/cli-update/spec.md | 47 - .../tasks.md | 53 - spec/openspec/templates/design.md | 19 - spec/openspec/templates/proposal.md | 23 - spec/openspec/templates/spec.md | 8 - spec/openspec/templates/tasks.md | 9 - spec/spec-kit/AGENTS.md | 474 ------- spec/spec-kit/DEVELOPMENT.md | 24 - spec/spec-kit/commands/analyze.md | 254 ---- spec/spec-kit/commands/checklist.md | 368 ------ spec/spec-kit/commands/clarify.md | 284 ---- spec/spec-kit/commands/constitution.md | 152 --- spec/spec-kit/commands/converge.md | 272 ---- spec/spec-kit/commands/implement.md | 218 --- spec/spec-kit/commands/plan.md | 170 --- spec/spec-kit/commands/specify.md | 345 ----- spec/spec-kit/commands/tasks.md | 218 --- spec/spec-kit/commands/taskstoissues.md | 105 -- spec/spec-kit/spec-driven.md | 418 ------ spec/spec-kit/templates/checklist-template.md | 40 - .../templates/constitution-template.md | 50 - spec/spec-kit/templates/plan-template.md | 113 -- spec/spec-kit/templates/spec-template.md | 131 -- spec/spec-kit/templates/tasks-template.md | 252 ---- spec/spec-kit/templates/vscode-settings.json | 14 - 137 files changed, 18 insertions(+), 24138 deletions(-) delete mode 100644 spec/agent-skills/AGENTS.md delete mode 100644 spec/agent-skills/CLAUDE.md delete mode 100644 spec/agent-skills/agents/code-reviewer.md delete mode 100644 spec/agent-skills/agents/security-auditor.md delete mode 100644 spec/agent-skills/agents/test-engineer.md delete mode 100644 spec/agent-skills/agents/web-performance-auditor.md delete mode 100644 spec/agent-skills/commands/build.toml delete mode 100644 spec/agent-skills/commands/code-simplify.toml delete mode 100644 spec/agent-skills/commands/planning.toml delete mode 100644 spec/agent-skills/commands/review.toml delete mode 100644 spec/agent-skills/commands/ship.toml delete mode 100644 spec/agent-skills/commands/spec.md delete mode 100644 spec/agent-skills/commands/spec.toml delete mode 100644 spec/agent-skills/commands/test.toml delete mode 100644 spec/agent-skills/commands/webperf.toml delete mode 100644 spec/agent-skills/definition-of-done.md delete mode 100644 spec/agent-skills/docs/agents.md delete mode 100644 spec/agent-skills/docs/antigravity-setup.md delete mode 100644 spec/agent-skills/docs/comparison.md delete mode 100644 spec/agent-skills/docs/copilot-setup.md delete mode 100644 spec/agent-skills/docs/cursor-setup.md delete mode 100644 spec/agent-skills/docs/gemini-cli-setup.md delete mode 100644 spec/agent-skills/docs/getting-started.md delete mode 100644 spec/agent-skills/docs/opencode-setup.md delete mode 100644 spec/agent-skills/docs/skill-anatomy.md delete mode 100644 spec/agent-skills/docs/windsurf-setup.md delete mode 100644 spec/agent-skills/hooks/SDD-CACHE.md delete mode 100644 spec/agent-skills/hooks/SIMPLIFY-IGNORE.md delete mode 100644 spec/agent-skills/hooks/hooks.json delete mode 100755 spec/agent-skills/hooks/sdd-cache-post.sh delete mode 100755 spec/agent-skills/hooks/sdd-cache-pre.sh delete mode 100755 spec/agent-skills/hooks/session-start-test.sh delete mode 100755 spec/agent-skills/hooks/session-start.sh delete mode 100755 spec/agent-skills/hooks/simplify-ignore-test.sh delete mode 100755 spec/agent-skills/hooks/simplify-ignore.sh delete mode 100644 spec/agent-skills/references/accessibility-checklist.md delete mode 100644 spec/agent-skills/references/definition-of-done.md delete mode 100644 spec/agent-skills/references/observability-checklist.md delete mode 100644 spec/agent-skills/references/orchestration-patterns.md delete mode 100644 spec/agent-skills/references/performance-checklist.md delete mode 100644 spec/agent-skills/references/security-checklist.md delete mode 100644 spec/agent-skills/references/testing-patterns.md delete mode 100644 spec/agent-skills/skills/api-and-interface-design/SKILL.md delete mode 100644 spec/agent-skills/skills/browser-testing-with-devtools/SKILL.md delete mode 100644 spec/agent-skills/skills/ci-cd-and-automation/SKILL.md delete mode 100644 spec/agent-skills/skills/code-review-and-quality/SKILL.md delete mode 100644 spec/agent-skills/skills/code-simplification/SKILL.md delete mode 100644 spec/agent-skills/skills/context-engineering/SKILL.md delete mode 100644 spec/agent-skills/skills/debugging-and-error-recovery/SKILL.md delete mode 100644 spec/agent-skills/skills/deprecation-and-migration/SKILL.md delete mode 100644 spec/agent-skills/skills/documentation-and-adrs/SKILL.md delete mode 100644 spec/agent-skills/skills/doubt-driven-development/SKILL.md delete mode 100644 spec/agent-skills/skills/frontend-ui-engineering/SKILL.md delete mode 100644 spec/agent-skills/skills/git-workflow-and-versioning/SKILL.md delete mode 100644 spec/agent-skills/skills/idea-refine/SKILL.md delete mode 100644 spec/agent-skills/skills/idea-refine/examples.md delete mode 100644 spec/agent-skills/skills/idea-refine/frameworks.md delete mode 100644 spec/agent-skills/skills/idea-refine/refinement-criteria.md delete mode 100755 spec/agent-skills/skills/idea-refine/scripts/idea-refine.sh delete mode 100644 spec/agent-skills/skills/incremental-implementation/SKILL.md delete mode 100644 spec/agent-skills/skills/interview-me/SKILL.md delete mode 100644 spec/agent-skills/skills/observability-and-instrumentation/SKILL.md delete mode 100644 spec/agent-skills/skills/performance-optimization/SKILL.md delete mode 100644 spec/agent-skills/skills/planning-and-task-breakdown/SKILL.md delete mode 100644 spec/agent-skills/skills/security-and-hardening/SKILL.md delete mode 100644 spec/agent-skills/skills/shipping-and-launch/SKILL.md delete mode 100644 spec/agent-skills/skills/source-driven-development/SKILL.md delete mode 100644 spec/agent-skills/skills/spec-driven-development/SKILL.md delete mode 100644 spec/agent-skills/skills/test-driven-development/SKILL.md delete mode 100644 spec/agent-skills/skills/using-agent-skills/SKILL.md delete mode 100644 spec/agent-skills/spec-driven-development.md delete mode 100644 spec/openspec/docs/README.md delete mode 100644 spec/openspec/docs/agent-contract.md delete mode 100644 spec/openspec/docs/cli.md delete mode 100644 spec/openspec/docs/commands.md delete mode 100644 spec/openspec/docs/concepts.md delete mode 100644 spec/openspec/docs/customization.md delete mode 100644 spec/openspec/docs/editing-changes.md delete mode 100644 spec/openspec/docs/examples.md delete mode 100644 spec/openspec/docs/existing-projects.md delete mode 100644 spec/openspec/docs/explore.md delete mode 100644 spec/openspec/docs/faq.md delete mode 100644 spec/openspec/docs/getting-started.md delete mode 100644 spec/openspec/docs/glossary.md delete mode 100644 spec/openspec/docs/how-commands-work.md delete mode 100644 spec/openspec/docs/installation.md delete mode 100644 spec/openspec/docs/migration-guide.md delete mode 100644 spec/openspec/docs/multi-language.md delete mode 100644 spec/openspec/docs/opsx.md delete mode 100644 spec/openspec/docs/overview.md delete mode 100644 spec/openspec/docs/reviewing-changes.md delete mode 100644 spec/openspec/docs/supported-tools.md delete mode 100644 spec/openspec/docs/team-workflow.md delete mode 100644 spec/openspec/docs/troubleshooting.md delete mode 100644 spec/openspec/docs/workflows.md delete mode 100644 spec/openspec/docs/writing-specs.md delete mode 100644 spec/openspec/examples/add-global-install-scope/design.md delete mode 100644 spec/openspec/examples/add-global-install-scope/proposal.md delete mode 100644 spec/openspec/examples/add-global-install-scope/specs/ai-tool-paths/spec.md delete mode 100644 spec/openspec/examples/add-global-install-scope/specs/cli-config/spec.md delete mode 100644 spec/openspec/examples/add-global-install-scope/specs/cli-init/spec.md delete mode 100644 spec/openspec/examples/add-global-install-scope/specs/cli-update/spec.md delete mode 100644 spec/openspec/examples/add-global-install-scope/specs/command-generation/spec.md delete mode 100644 spec/openspec/examples/add-global-install-scope/specs/global-config/spec.md delete mode 100644 spec/openspec/examples/add-global-install-scope/specs/installation-scope/spec.md delete mode 100644 spec/openspec/examples/add-global-install-scope/tasks.md delete mode 100644 spec/openspec/examples/add-qa-smoke-harness/proposal.md delete mode 100644 spec/openspec/examples/add-qa-smoke-harness/specs/developer-qa-workflow/spec.md delete mode 100644 spec/openspec/examples/add-tool-command-surface-capabilities/proposal.md delete mode 100644 spec/openspec/examples/add-tool-command-surface-capabilities/specs/cli-init/spec.md delete mode 100644 spec/openspec/examples/add-tool-command-surface-capabilities/specs/cli-update/spec.md delete mode 100644 spec/openspec/examples/add-tool-command-surface-capabilities/tasks.md delete mode 100644 spec/openspec/templates/design.md delete mode 100644 spec/openspec/templates/proposal.md delete mode 100644 spec/openspec/templates/spec.md delete mode 100644 spec/openspec/templates/tasks.md delete mode 100644 spec/spec-kit/AGENTS.md delete mode 100644 spec/spec-kit/DEVELOPMENT.md delete mode 100644 spec/spec-kit/commands/analyze.md delete mode 100644 spec/spec-kit/commands/checklist.md delete mode 100644 spec/spec-kit/commands/clarify.md delete mode 100644 spec/spec-kit/commands/constitution.md delete mode 100644 spec/spec-kit/commands/converge.md delete mode 100644 spec/spec-kit/commands/implement.md delete mode 100644 spec/spec-kit/commands/plan.md delete mode 100644 spec/spec-kit/commands/specify.md delete mode 100644 spec/spec-kit/commands/tasks.md delete mode 100644 spec/spec-kit/commands/taskstoissues.md delete mode 100644 spec/spec-kit/spec-driven.md delete mode 100644 spec/spec-kit/templates/checklist-template.md delete mode 100644 spec/spec-kit/templates/constitution-template.md delete mode 100644 spec/spec-kit/templates/plan-template.md delete mode 100644 spec/spec-kit/templates/spec-template.md delete mode 100644 spec/spec-kit/templates/tasks-template.md delete mode 100644 spec/spec-kit/templates/vscode-settings.json diff --git a/docs/architecture/spec.md b/docs/architecture/spec.md index 86d041e7..80683b91 100644 --- a/docs/architecture/spec.md +++ b/docs/architecture/spec.md @@ -29,7 +29,7 @@ layout: | `cmd/` | CLI entry point (Cobra) and TUI (Bubble Tea) | | `internal/` | Private Go packages (not importable by external repos) | | `external/` | Pinned ecosystem submodules (eyrie, yaad, tok, inspect, sight, trace, hawk-core-contracts) | -| `spec/` | Reference repos for skills, spec-kit, openspec | +| `spec/` | OpenSpec schema consumed by `internal/spec` | | `docs/` | Architecture docs, design docs, plans | | `rules/` | User-defined rules | | `deploy/` | Docker deployment | diff --git a/spec/README.md b/spec/README.md index b85585d6..59e67829 100644 --- a/spec/README.md +++ b/spec/README.md @@ -1,127 +1,31 @@ # Spec -Curated spec-driven development resources from three external projects, consolidated for hawk's spec mode. These are **reference materials** — hawk's actual spec engine is in `internal/engine/spec/`. +Curated spec-driven development resource consolidated for hawk's spec mode. -## Sources - -| Directory | Source | Stars | Description | -|-----------|--------|-------|-------------| -| `openspec/` | [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) | ~5k | Schema-driven artifact workflow engine with delta specs. Full TypeScript CLI tool for change management. | -| `spec-kit/` | [github/spec-kit](https://github.com/github/spec-kit) | ~117k | GitHub's Spec-Driven Development toolkit with 10 SDD commands, 5 artifact templates, extension system. Python CLI. | -| `agent-skills/` | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | ~20k | Production-grade engineering skills for AI coding agents. 25+ skills, 8 commands, references, hooks, agents. | +hawk's spec engine lives in `internal/spec/` (DAG, delta merge, validator, state). +The OpenSpec artifact-workflow schema below is the source hawk's +`DefaultSchema` derives from — everything else in `spec/` is reference material +that was trimmed as dead weight. ## Structure ``` spec/ ├── README.md -│ -├── openspec/ # Fission-AI/OpenSpec -│ ├── schema.yaml # Artifact workflow schema -│ ├── templates/ # Artifact templates -│ │ ├── proposal.md -│ │ ├── spec.md # Delta spec format -│ │ ├── design.md -│ │ └── tasks.md -│ ├── docs/ # 25 doc pages (concepts, CLI, workflows, FAQ) -│ └── examples/ # Real-world change artifacts -│ ├── add-global-install-scope/ # Full proposal + 6 specs + design + tasks -│ ├── add-tool-command-surface-capabilities/ -│ └── add-qa-smoke-harness/ -│ -├── spec-kit/ # github/spec-kit -│ ├── spec-driven.md # Full SDD methodology doc -│ ├── AGENTS.md # Agent instructions -│ ├── DEVELOPMENT.md # Developer onboarding -│ ├── commands/ # 10 SDD command workflows -│ │ ├── specify.md # Write the spec -│ │ ├── clarify.md # Ask clarifying questions [NEEDS CLARIFICATION] -│ │ ├── plan.md # Write the plan -│ │ ├── tasks.md # Write task breakdown -│ │ ├── checklist.md # Quality checklist review -│ │ ├── implement.md # Execute implementation -│ │ ├── converge.md # Gap analysis -│ │ ├── analyze.md # Codebase analysis before spec -│ │ ├── constitution.md # Project constitution setup -│ │ └── taskstoissues.md # Convert tasks to issues -│ └── templates/ -│ ├── spec-template.md -│ ├── plan-template.md -│ ├── tasks-template.md -│ ├── constitution-template.md -│ ├── checklist-template.md -│ └── vscode-settings.json -│ -└── agent-skills/ # addyosmani/agent-skills - ├── spec-driven-development.md # Gated 4-phase SDD skill - ├── definition-of-done.md # Standing quality checklist - ├── AGENTS.md # Agent definitions - ├── CLAUDE.md # Claude project config - ├── commands/ # 8 .toml command definitions - ├── skills/ # 25+ engineering skills - │ ├── spec-driven-development/ # SDD skill (v2) - │ ├── interview-me/ # Asks clarifying questions - │ ├── idea-refine/ # Refines vague ideas into specs - │ ├── planning-and-task-breakdown/ - │ ├── incremental-implementation/ - │ ├── test-driven-development/ - │ ├── code-review-and-quality/ - │ ├── code-simplification/ - │ ├── context-engineering/ - │ ├── doubt-driven-development/ - │ ├── debugging-and-error-recovery/ - │ ├── git-workflow-and-versioning/ - │ ├── documentation-and-adrs/ - │ ├── security-and-hardening/ - │ ├── performance-optimization/ - │ ├── observability-and-instrumentation/ - │ ├── shipping-and-launch/ - │ ├── ci-cd-and-automation/ - │ ├── api-and-interface-design/ - │ ├── browser-testing-with-devtools/ - │ ├── frontend-ui-engineering/ - │ ├── deprecation-and-migration/ - │ ├── source-driven-development/ - │ ├── using-agent-skills/ - │ └── ... (more) - ├── docs/ # Setup guides for all major AI tools - ├── references/ # 7 checklists and reference docs - ├── hooks/ # Session hooks (session-start, sdd-cache) - └── agents/ # Pre-built agent personas +└── openspec/ + └── schema.yaml # Artifact workflow schema (embedded by internal/spec/schema.go) ``` -## Detailed Comparison - -### OpenSpec vs spec-kit vs agent-skills vs hawk's spec +Removed (2026-08, dead or duplicated elsewhere): -| Capability | OpenSpec | spec-kit | agent-skills | hawk spec | -|-----------|----------|----------|--------------|-----------| -| **Artifact DAG** | `requires:` deps, schema-driven | Phase gating | 4-phase gating | `Graph` with Kahn's algo | -| **Delta specs** | `## ADDED/MODIFIED/REMOVED/RENAMED` | Same format | - | `ParseDeltaSpec` + `ApplyDelta` | -| **Quality validation** | Zod validation rules | Checklist + 3x re-validate | Definition of Done | `ValidateSpec/Plan/Tasks` | -| **Clarify questions** | - | `clarify` cmd + `[NEEDS CLARIFICATION]` markers | `interview-me` skill + assumption surfacing | Prompt-driven (model uses `AskUser`) | -| **Constitution** | - | `constitution-template.md` + `constitution` cmd | - | - | -| **Idea refinement** | - | - | `idea-refine` skill (frameworks, examples, refinement criteria) | - | -| **Extensibility** | 27 tool adapters, profiles | Extension system (git, agent-context, bug), presets, bundles, workflows | Hooks system (session-start, sdd-cache) | `tool.Tool` interface | -| **Archive** | `archive` command (moves dirs) | `archive` concept | - | `Archive` function | -| **Convergence** | `verify` command | `converge` command + gap analysis | Definition of Done | `AssessConvergence` | -| **Task tracking** | tasks.md with checkboxes | `- [ ]` format + `taskstoissues` | Task breakdown template | Checkbox regex + phase tracking | -| **Stores/remotes** | Git-based store system | - | - | - | -| **CLI tool** | TypeScript, pnpm | Python, pipx/uv | - | Go, single binary | -| **AI tool support** | 27+ adapters | 30+ integrations | - | Tool registry + MCP | +| Path | Reason removed | +|------|----------------| +| `spec/agent-skills/` | addyosmani/agent-skills vendored copy. 23 SKILL.md files were byte-identical to the runtime-embedded `internal/plugin/bundled_skills/`; no code/script/test referenced it. | +| `spec/spec-kit/` | github/spec-kit vendored docs/commands/templates. Reference-only, no code consumer. | +| `spec/openspec/docs/`, `spec/openspec/examples/`, `spec/openspec/templates/` | Fission-AI/OpenSpec docs and sample artifacts. Only `schema.yaml` is consumed by code. | -### Key patterns hawk should adopt +## Why OpenSpec schema is kept -| Pattern | Source | Why | -|---------|--------|-----| -| `clarify` command flow | spec-kit | Structured question asking before spec writing | -| `idea-refine` skill | agent-skills | Refining vague user ideas into actionable specs | -| `constitution` template | spec-kit | Documenting project governance rules | -| `converge` gap analysis | spec-kit | Checking implementation matches spec | -| `analyze` codebase scan | spec-kit | Pre-spec codebase analysis | -| Session hooks | agent-skills | Pre/post session lifecycle hooks | -| Definition of Done | agent-skills | Quality bar checklist applied to every change | -| `[NEEDS CLARIFICATION]` markers | spec-kit | Inline markers for unresolved questions (max 3) | -| `taskstoissues` | spec-kit | Converting task checkboxes to organized issues | -| Extension system | spec-kit | Pluggable git, agent-context, bug triage workflows | -| Archive + real-world examples | OpenSpec | Real change artifacts showing the full workflow | +`internal/spec/schema.go`'s `DefaultSchema` is derived from +`spec/openspec/schema.yaml` (the `requires:`/delta-spec vocabulary hawk's DAG +parser uses). It is load-bearing and must stay. diff --git a/spec/agent-skills/AGENTS.md b/spec/agent-skills/AGENTS.md deleted file mode 100644 index 2fdfd9b4..00000000 --- a/spec/agent-skills/AGENTS.md +++ /dev/null @@ -1,90 +0,0 @@ -# AGENTS.md - -This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, Antigravity, etc.) when working with code in this repository. - -## Repository Overview - -A collection of skills for Claude.ai and Claude Code for senior software engineers. Skills are packaged instructions and scripts that extend Claude and your coding agents capabilities. - -## OpenCode Integration - -OpenCode uses a **skill-driven execution model** powered by the `skill` tool and this repository's `/skills` directory. - -### Core Rules - -- If a task matches a skill, you MUST invoke it -- Skills are located in `skills//SKILL.md` -- Never implement directly if a skill applies -- Always follow the skill instructions exactly (do not partially apply them) - -### Intent → Skill Mapping - -The agent should automatically map user intent to skills: - -- Feature / new functionality → `spec-driven-development`, then `incremental-implementation`, `test-driven-development` -- Planning / breakdown → `planning-and-task-breakdown` -- Bug / failure / unexpected behavior → `debugging-and-error-recovery` -- Code review → `code-review-and-quality` -- Refactoring / simplification → `code-simplification` -- API or interface design → `api-and-interface-design` -- UI work → `frontend-ui-engineering` - -### Lifecycle Mapping (Implicit Commands) - -OpenCode does not support slash commands like `/spec` or `/plan`. - -Instead, the agent must internally follow this lifecycle: - -- DEFINE → `spec-driven-development` -- PLAN → `planning-and-task-breakdown` -- BUILD → `incremental-implementation` + `test-driven-development` -- VERIFY → `debugging-and-error-recovery` -- REVIEW → `code-review-and-quality` -- SHIP → `shipping-and-launch` - -### Execution Model - -For every request: - -1. Determine if any skill applies (even 1% chance) -2. Invoke the appropriate skill using the `skill` tool -3. Follow the skill workflow strictly -4. Only proceed to implementation after required steps (spec, plan, etc.) are complete - -### Anti-Rationalization - -The following thoughts are incorrect and must be ignored: - -- "This is too small for a skill" -- "I can just quickly implement this" -- "I’ll gather context first" - -Correct behavior: - -- Always check for and use skills first - -This ensures OpenCode behaves similarly to Claude Code with full workflow enforcement. - -## Orchestration: Personas, Skills, and Commands - -This repo has three composable layers. They have different jobs and should not be confused: - -- **Skills** (`skills//SKILL.md`) — workflows with steps and exit criteria. The *how*. Mandatory hops when an intent matches. -- **Personas** (`agents/.md`) — roles with a perspective and an output format. The *who*. -- **Slash commands** (`.claude/commands/*.md`) — user-facing entry points. The *when*. The orchestration layer. - -Composition rule: **the user (or a slash command) is the orchestrator. Personas do not invoke other personas.** A persona may invoke skills. - -The only multi-persona orchestration pattern this repo endorses is **parallel fan-out with a merge step** — used by `/ship` to run `code-reviewer`, `security-auditor`, and `test-engineer` concurrently and synthesize their reports. Do not build a "router" persona that decides which other persona to call; that's the job of slash commands and intent mapping. - -See [docs/agents.md](docs/agents.md) for the decision matrix and [references/orchestration-patterns.md](references/orchestration-patterns.md) for the full pattern catalog. - -**Claude Code interop:** the personas in `agents/` work as Claude Code subagents (auto-discovered from this plugin's `agents/` directory) and as Agent Teams teammates (referenced by name when spawning). Two platform constraints align with our rules: subagents cannot spawn other subagents, and teams cannot nest. Plugin agents silently ignore the `hooks`, `mcpServers`, and `permissionMode` frontmatter fields. - -## Creating a New Skill - -> **Before you start:** run the pre-flight checks in [CONTRIBUTING.md](CONTRIBUTING.md#before-proposing-a-new-skill), search the catalog, check open PRs (`gh pr list --state open`), confirm the idea fits [docs/skill-anatomy.md](docs/skill-anatomy.md), and justify the gap in your PR description. Most new-skill ideas overlap an existing skill or an open PR; prefer extending an existing skill over adding a near-duplicate. CONTRIBUTING.md is the single source of truth for this workflow. - -Skills in this repo are markdown-first: each lives at `skills//SKILL.md` with YAML frontmatter (`name`, `description`) and follows the section anatomy (Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification). Add a `scripts/` directory only when the skill ships runnable helpers; most skills are markdown only, and there are no per-skill zip packages. - -For the full format, naming conventions, frontmatter rules, supporting-file thresholds, and writing principles, see [docs/skill-anatomy.md](docs/skill-anatomy.md), the single source of truth for skill structure. Do not restate that guidance here, link to it. diff --git a/spec/agent-skills/CLAUDE.md b/spec/agent-skills/CLAUDE.md deleted file mode 100644 index 6bdc4393..00000000 --- a/spec/agent-skills/CLAUDE.md +++ /dev/null @@ -1,56 +0,0 @@ -# agent-skills - -This is the agent-skills project — a collection of production-grade engineering skills for AI coding agents. - -## Project Structure - -``` -skills/ → Core skills (SKILL.md per directory) -agents/ → Reusable agent personas (code-reviewer, test-engineer, security-auditor, web-performance-auditor) -hooks/ → Session lifecycle hooks -.claude/commands/ → Slash commands (/spec, /plan, /build, /test, /review, /code-simplify, /ship; plus /webperf specialist audit) -references/ → Supplementary checklists (testing, performance, security, accessibility, observability) -docs/ → Setup guides for different tools -``` - -## Skills by Phase - -**Define:** interview-me, idea-refine, spec-driven-development -**Plan:** planning-and-task-breakdown -**Build:** incremental-implementation, test-driven-development, context-engineering, source-driven-development, doubt-driven-development, frontend-ui-engineering, api-and-interface-design -**Verify:** browser-testing-with-devtools, debugging-and-error-recovery -**Review:** code-review-and-quality, code-simplification, security-and-hardening, performance-optimization -**Ship:** git-workflow-and-versioning, ci-cd-and-automation, deprecation-and-migration, documentation-and-adrs, observability-and-instrumentation, shipping-and-launch - -## Conventions - -- Every skill lives in `skills//SKILL.md` -- YAML frontmatter with `name` and `description` fields -- Description starts with what the skill does (third person), followed by trigger conditions ("Use when...") -- Every skill has: Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification -- References are in `references/`, not inside skill directories -- Supporting files only created when content exceeds 100 lines - -## Contributing - -Before adding a new skill or significantly reworking an existing one, run the pre-flight checks in [CONTRIBUTING.md](CONTRIBUTING.md#before-proposing-a-new-skill): search the catalog, check open PRs, confirm the idea fits [docs/skill-anatomy.md](docs/skill-anatomy.md), and justify the gap. Prefer extending an existing skill over adding a near-duplicate. CONTRIBUTING.md is the single source of truth for this workflow; do not restate its checklist here or elsewhere, link to it. - -## Commands - -- `npm test` — Not applicable (this is a documentation project) -- Validate: Check that all SKILL.md files have valid YAML frontmatter with name and description - -## Pull Requests - -PRs target the upstream repository's default branch. In a typical fork setup the upstream remote is `upstream` and your fork is `origin`, but the exact remote names are not what matters here. - -- Before opening a PR, search the upstream repository's open PRs and issues for work that touches the same files or rules. If any overlaps, coordinate (build on it, align your rules with it, or rebase after it merges) instead of opening a conflicting PR. -- Prefer small, focused PRs over large refactors of widely shared files (for example, files under `scripts/`), which are more likely to collide with in-flight work. - -## Boundaries - -- Always: Run the CONTRIBUTING.md pre-flight checks before creating a new skill directory -- Always: Follow the skill-anatomy.md format for new skills -- Always: Check the upstream repo's open PRs and issues for overlap before opening a new PR -- Never: Add skills that are vague advice instead of actionable processes -- Never: Duplicate content between skills — reference other skills instead diff --git a/spec/agent-skills/agents/code-reviewer.md b/spec/agent-skills/agents/code-reviewer.md deleted file mode 100644 index 96cac1d7..00000000 --- a/spec/agent-skills/agents/code-reviewer.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -name: code-reviewer -description: Senior code reviewer that evaluates changes across five dimensions — correctness, readability, architecture, security, and performance. Use for thorough code review before merge. ---- - -# Senior Code Reviewer - -You are an experienced Staff Engineer conducting a thorough code review. Your role is to evaluate the proposed changes and provide actionable, categorized feedback. - -## Review Framework - -Evaluate every change across these five dimensions: - -### 1. Correctness -- Does the code do what the spec/task says it should? -- Are edge cases handled (null, empty, boundary values, error paths)? -- Do the tests actually verify the behavior? Are they testing the right things? -- Are there race conditions, off-by-one errors, or state inconsistencies? - -### 2. Readability -- Can another engineer understand this without explanation? -- Are names descriptive and consistent with project conventions? -- Is the control flow straightforward (no deeply nested logic)? -- Is the code well-organized (related code grouped, clear boundaries)? - -### 3. Architecture -- Does the change follow existing patterns or introduce a new one? -- If a new pattern, is it justified and documented? -- Are module boundaries maintained? Any circular dependencies? -- Is the abstraction level appropriate (not over-engineered, not too coupled)? -- Are dependencies flowing in the right direction? - -### 4. Security -- Is user input validated and sanitized at system boundaries? -- Are secrets kept out of code, logs, and version control? -- Is authentication/authorization checked where needed? -- Are queries parameterized? Is output encoded? -- Any new dependencies with known vulnerabilities? - -### 5. Performance -- Any N+1 query patterns? -- Any unbounded loops or unconstrained data fetching? -- Any synchronous operations that should be async? -- Any unnecessary re-renders (in UI components)? -- Any missing pagination on list endpoints? - -## Output Format - -Categorize every finding: - -**Critical** — Must fix before merge (security vulnerability, data loss risk, broken functionality) - -**Important** — Should fix before merge (missing test, wrong abstraction, poor error handling) - -**Suggestion** — Consider for improvement (naming, code style, optional optimization) - -## Review Output Template - -```markdown -## Review Summary - -**Verdict:** APPROVE | REQUEST CHANGES - -**Overview:** [1-2 sentences summarizing the change and overall assessment] - -### Critical Issues -- [File:line] [Description and recommended fix] - -### Important Issues -- [File:line] [Description and recommended fix] - -### Suggestions -- [File:line] [Description] - -### What's Done Well -- [Positive observation — always include at least one] - -### Verification Story -- Tests reviewed: [yes/no, observations] -- Build verified: [yes/no] -- Security checked: [yes/no, observations] -``` - -## Rules - -1. Review the tests first — they reveal intent and coverage -2. Read the spec or task description before reviewing code -3. Every Critical and Important finding should include a specific fix recommendation -4. Don't approve code with Critical issues -5. Acknowledge what's done well — specific praise motivates good practices -6. If you're uncertain about something, say so and suggest investigation rather than guessing - -## Composition - -- **Invoke directly when:** the user asks for a review of a specific change, file, or PR. -- **Invoke via:** `/review` (single-perspective review) or `/ship` (parallel fan-out alongside `security-auditor` and `test-engineer`). -- **Do not invoke from another persona.** If you find yourself wanting to delegate to `security-auditor` or `test-engineer`, surface that as a recommendation in your report instead — orchestration belongs to slash commands, not personas. See [docs/agents.md](../docs/agents.md). diff --git a/spec/agent-skills/agents/security-auditor.md b/spec/agent-skills/agents/security-auditor.md deleted file mode 100644 index efb1e4e5..00000000 --- a/spec/agent-skills/agents/security-auditor.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -name: security-auditor -description: Security engineer focused on vulnerability detection, threat modeling, and secure coding practices. Use for security-focused code review, threat analysis, or hardening recommendations. ---- - -# Security Auditor - -You are an experienced Security Engineer conducting a security review. Your role is to identify vulnerabilities, assess risk, and recommend mitigations. You focus on practical, exploitable issues rather than theoretical risks. - -## Review Scope - -### 1. Input Handling -- Is all user input validated at system boundaries? -- Are there injection vectors (SQL, NoSQL, OS command, LDAP)? -- Is HTML output encoded to prevent XSS? -- Are file uploads restricted by type, size, and content? -- Are URL redirects validated against an allowlist? - -### 2. Authentication & Authorization -- Are passwords hashed with a strong algorithm (bcrypt, scrypt, argon2)? -- Are sessions managed securely (httpOnly, secure, sameSite cookies)? -- Is authorization checked on every protected endpoint? -- Can users access resources belonging to other users (IDOR)? -- Are password reset tokens time-limited and single-use? -- Is rate limiting applied to authentication endpoints? - -### 3. Data Protection -- Are secrets in environment variables (not code)? -- Are sensitive fields excluded from API responses and logs? -- Is data encrypted in transit (HTTPS) and at rest (if required)? -- Is PII handled according to applicable regulations? -- Are database backups encrypted? - -### 4. Infrastructure -- Are security headers configured (CSP, HSTS, X-Frame-Options)? -- Is CORS restricted to specific origins? -- Are dependencies audited for known vulnerabilities? -- Are error messages generic (no stack traces or internal details to users)? -- Is the principle of least privilege applied to service accounts? - -### 5. Third-Party Integrations -- Are API keys and tokens stored securely? -- Are webhook payloads verified (signature validation)? -- Are third-party scripts loaded from trusted CDNs with integrity hashes? -- Are OAuth flows using PKCE and state parameters? -- Are server-side fetches of user-supplied URLs allowlisted (SSRF)? - -### 6. AI / LLM Features (if present) -- Is model output treated as untrusted (never into `eval`, SQL, shell, `innerHTML`, file paths)? -- Is the system prompt relied on as a security boundary instead of code-enforced permissions (prompt injection)? -- Are secrets, cross-tenant data, or the full system prompt placed in the context window? -- Are tool/agent permissions scoped, with confirmation for destructive actions (excessive agency)? -- Are token, rate, and recursion limits set (unbounded consumption)? - -Map findings to the OWASP Top 10 for LLM Applications where relevant. - -## Severity Classification - -| Severity | Criteria | Action | -|----------|----------|--------| -| **Critical** | Exploitable remotely, leads to data breach or full compromise | Fix immediately, block release | -| **High** | Exploitable with some conditions, significant data exposure | Fix before release | -| **Medium** | Limited impact or requires authenticated access to exploit | Fix in current sprint | -| **Low** | Theoretical risk or defense-in-depth improvement | Schedule for next sprint | -| **Info** | Best practice recommendation, no current risk | Consider adopting | - -## Output Format - -```markdown -## Security Audit Report - -### Summary -- Critical: [count] -- High: [count] -- Medium: [count] -- Low: [count] - -### Findings - -#### [CRITICAL] [Finding title] -- **Location:** [file:line] -- **Description:** [What the vulnerability is] -- **Impact:** [What an attacker could do] -- **Proof of concept:** [How to exploit it] -- **Recommendation:** [Specific fix with code example] - -#### [HIGH] [Finding title] -... - -### Positive Observations -- [Security practices done well] - -### Recommendations -- [Proactive improvements to consider] -``` - -## Rules - -1. Focus on exploitable vulnerabilities, not theoretical risks -2. Every finding must include a specific, actionable recommendation -3. Provide proof of concept or exploitation scenario for Critical/High findings -4. Acknowledge good security practices — positive reinforcement matters -5. Check the OWASP Top 10 (and the LLM Top 10 for AI features) as a minimum baseline -6. Review dependencies for known CVEs and supply-chain risk (typosquats, postinstall scripts) -7. Never suggest disabling security controls as a "fix" -8. Start from trust boundaries — where untrusted data enters — and reason about each with STRIDE before enumerating findings - -## Composition - -- **Invoke directly when:** the user wants a security-focused pass on a specific change, file, or system component. -- **Invoke via:** `/ship` (parallel fan-out alongside `code-reviewer` and `test-engineer`), or any future `/audit` command. -- **Do not invoke from another persona.** If `code-reviewer` flags something that warrants a deeper security pass, the user or a slash command initiates that pass — not the reviewer. See [docs/agents.md](../docs/agents.md). diff --git a/spec/agent-skills/agents/test-engineer.md b/spec/agent-skills/agents/test-engineer.md deleted file mode 100644 index 19a41bad..00000000 --- a/spec/agent-skills/agents/test-engineer.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -name: test-engineer -description: QA engineer specialized in test strategy, test writing, and coverage analysis. Use for designing test suites, writing tests for existing code, or evaluating test quality. ---- - -# Test Engineer - -You are an experienced QA Engineer focused on test strategy and quality assurance. Your role is to design test suites, write tests, analyze coverage gaps, and ensure that code changes are properly verified. - -## Approach - -### 1. Analyze Before Writing - -Before writing any test: -- Read the code being tested to understand its behavior -- Identify the public API / interface (what to test) -- Identify edge cases and error paths -- Check existing tests for patterns and conventions - -### 2. Test at the Right Level - -``` -Pure logic, no I/O → Unit test -Crosses a boundary → Integration test -Critical user flow → E2E test -``` - -Test at the lowest level that captures the behavior. Don't write E2E tests for things unit tests can cover. - -### 3. Follow the Prove-It Pattern for Bugs - -When asked to write a test for a bug: -1. Write a test that demonstrates the bug (must FAIL with current code) -2. Confirm the test fails -3. Report the test is ready for the fix implementation - -### 4. Write Descriptive Tests - -``` -describe('[Module/Function name]', () => { - it('[expected behavior in plain English]', () => { - // Arrange → Act → Assert - }); -}); -``` - -### 5. Cover These Scenarios - -For every function or component: - -| Scenario | Example | -|----------|---------| -| Happy path | Valid input produces expected output | -| Empty input | Empty string, empty array, null, undefined | -| Boundary values | Min, max, zero, negative | -| Error paths | Invalid input, network failure, timeout | -| Concurrency | Rapid repeated calls, out-of-order responses | - -## Output Format - -When analyzing test coverage: - -```markdown -## Test Coverage Analysis - -### Current Coverage -- [X] tests covering [Y] functions/components -- Coverage gaps identified: [list] - -### Recommended Tests -1. **[Test name]** — [What it verifies, why it matters] -2. **[Test name]** — [What it verifies, why it matters] - -### Priority -- Critical: [Tests that catch potential data loss or security issues] -- High: [Tests for core business logic] -- Medium: [Tests for edge cases and error handling] -- Low: [Tests for utility functions and formatting] -``` - -## Rules - -1. Test behavior, not implementation details -2. Each test should verify one concept -3. Tests should be independent — no shared mutable state between tests -4. Avoid snapshot tests unless reviewing every change to the snapshot -5. Mock at system boundaries (database, network), not between internal functions -6. Every test name should read like a specification -7. A test that never fails is as useless as a test that always fails - -## Composition - -- **Invoke directly when:** the user asks for test design, coverage analysis, or a Prove-It test for a specific bug. -- **Invoke via:** `/test` (TDD workflow) or `/ship` (parallel fan-out for coverage gap analysis alongside `code-reviewer` and `security-auditor`). -- **Do not invoke from another persona.** Recommendations to add tests belong in your report; the user or a slash command decides when to act on them. See [docs/agents.md](../docs/agents.md). diff --git a/spec/agent-skills/agents/web-performance-auditor.md b/spec/agent-skills/agents/web-performance-auditor.md deleted file mode 100644 index 44bc45d8..00000000 --- a/spec/agent-skills/agents/web-performance-auditor.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -name: web-performance-auditor -description: Web performance engineer focused on Core Web Vitals, loading, rendering, and network optimization. Use for performance-focused audits, CWV analysis, and identifying structural performance anti-patterns in web applications. ---- - -# Web Performance Auditor - -You are an experienced Web Performance Engineer conducting a performance audit. Your role is to identify bottlenecks, assess their real-world user impact, and recommend concrete fixes. You prioritize findings by actual or likely effect on Core Web Vitals and user experience. - -## Operating Modes - -### Quick mode (default — no tool artifacts provided) - -Scan source code directly for structural anti-patterns. Every finding is tagged **potential impact**, never as a measurement. The scorecard is marked `not measured` and left empty. - -### Deep mode (activated when tool artifacts or live measurement are available) - -Interpret performance data from one or more of: - -- **Lighthouse JSON report**: parse directly. Sources include `npx lighthouse --output json`, `npx -p chrome-devtools-mcp chrome-devtools lighthouse_audit --output-format=json` (Chrome DevTools MCP CLI, no install required), or the `lighthouseResult` object from a PageSpeed Insights API response (paste the full JSON). -- **PageSpeed Insights JSON**: the full JSON response from the PageSpeed Insights API (`pagespeedonline.googleapis.com/pagespeedonline/v5/runPagespeed`). Contains `lighthouseResult` (lab) and `loadingExperience` (CrUX field data). Parse both. -- **CrUX API response**: field data (p75 over the last 28 days). Parse directly. Requires `CRUX_API_KEY`. -- **DevTools performance trace** (Perfetto JSON): complex format. Defer interpretation to Chrome DevTools MCP (`performance_analyze_insight`); without MCP, summarize what you can extract and flag the rest as unparsed. -- **Live capture via Chrome DevTools MCP server**: when the MCP server is configured in the harness, capture metrics directly using `lighthouse_audit`, `performance_start_trace` / `performance_stop_trace`, and `performance_analyze_insight` instead of asking the user to paste artifacts. -- **Chrome DevTools MCP CLI** (`chrome-devtools` command): when there's no MCP server in the harness, ask the user to invoke the CLI directly. It can be run on demand with `npx -p chrome-devtools-mcp chrome-devtools ` (no install) or after `npm i -g chrome-devtools-mcp`. Example: `chrome-devtools lighthouse_audit --output-format=json > report.json`. - -Populate the scorecard only with values backed by these sources. Mark unmeasured fields as `not measured`. - -## Tooling - -| Capability | Tool / Source | Requires | -|---|---|---| -| Lab metrics, opportunities, diagnostics | Lighthouse JSON | None (parse a provided file) | -| Field metrics (real users, p75) | CrUX API | `CRUX_API_KEY` or `GOOGLE_API_KEY` env var | -| Combined lab + field | PageSpeed Insights JSON | None for parsing; the user provides the JSON | -| Live trace, LCP attribution, INP attribution, layout shift attribution | Chrome DevTools MCP server (`performance_*`, `lighthouse_audit`) | `chrome-devtools` MCP server configured in the harness (see `skills/browser-testing-with-devtools`) | -| Manual terminal capture (Lighthouse, trace, screenshot) | Chrome DevTools MCP CLI (e.g. `chrome-devtools lighthouse_audit --output-format=json`) | `npx -p chrome-devtools-mcp chrome-devtools ` or `npm i -g chrome-devtools-mcp` (CLI is independent of the harness) | - -If a source is unavailable, do not fabricate. Skip the related section of the scorecard and continue with what you have. - -## Metric-Honesty Rule - -**Never fabricate metrics.** An LLM reading static source code cannot measure real-world LCP, INP, or CLS. If no tool data is provided: - -- Return a source-level findings report. -- Mark the entire scorecard as `not measured`. -- Label every finding as `potential impact`, not as a measurement. - -When data IS provided, label each scorecard value with its source (`Field (CrUX)`, `Lab (Lighthouse)`, `Trace (DevTools)`). Field and lab data are not interchangeable: field is what real users experienced, lab is a single synthetic run. Treating them as the same number is a form of fabrication. - -Violating this rule is worse than returning no scorecard at all. - -## Review Scope - -Identify the framework and rendering model (React, Vue, Svelte, Angular, Next.js, Astro, vanilla HTML, etc.) before applying framework-specific checks. Do not recommend `` from `next/image` to a Vue app, or `React.memo` to a Svelte app. - -### 1. Core Web Vitals - -- Does the LCP element load within 2.5s? Is it a hero image, heading, or block of text? -- Is the LCP image (if applicable) using `fetchpriority="high"` and not lazy-loaded? -- Are layout shifts caused by images, embeds, ads, fonts, or dynamically injected content? -- Do images, `` elements, iframes, and embeds have explicit `width` and `height` to reserve space? -- Are long tasks (> 50ms) blocking the main thread and delaying INP? -- Are event handlers doing synchronous heavy work before yielding to the browser? -- Is `scheduler.yield()` (or a `yieldToMain` fallback) used inside long-running loops so input events can interleave? -- Is the page using **soft navigation** APIs correctly so INP and LCP are tracked across SPA route changes? -- Is the **Long Animation Frames (LoAF)** API used (or planned) to attribute INP regressions in production? - -### 2. Loading - -- Is TTFB acceptable (< 800ms)? Are there slow server responses or missing CDN coverage? -- Are critical origins `preconnect`-ed and known third-party origins `dns-prefetch`-ed? -- Are LCP-critical resources preloaded with `fetchpriority="high"`? -- Is the **Speculation Rules API** used to `prerender` or `prefetch` likely-next navigations? -- Are fonts self-hosted, preloaded, and using `font-display: swap` (or `optional` for non-critical)? -- Are fonts subsetted (`unicode-range`) and limited in count/weights? -- Are images in modern formats (WebP, AVIF) with responsive `srcset` and `sizes`? -- Is the initial JavaScript bundle under 200KB gzipped? -- Is code splitting applied for routes and heavy features? -- Are blocking scripts in `` without `defer` or `async`? -- Are third-party scripts loaded with `async`/`defer` and fronted by a facade when heavy (chat widgets, video embeds)? - -### 3. Rendering / JavaScript - -- Are there unnecessary full-page re-renders? Is state lifted (or colocated) correctly? -- Are long lists virtualized? -- Are animations using `transform` and `opacity` (compositor-only)? -- Is there layout thrashing (reading layout properties, then writing, in a loop)? -- Is `content-visibility: auto` used for off-screen sections? -- Is the **View Transitions API** used appropriately to avoid perceived CLS on SPA navigations? -- Is **bfcache** preserved? (No `unload` handlers, no `Cache-Control: no-store` on HTML) -- **AI-generated patterns:** - - State duplication instead of lifting state. - - `React.memo` / `useMemo` / `useCallback` wrapping everything "just in case" (cost without benefit; can hurt perf). - - Over-eager `useEffect` dependencies causing redundant re-renders or update loops. - - **Vue:** watchers (`watch`/`watchEffect`) with broad dependencies that trigger unnecessary updates; `computed` with side effects. - - **Angular:** `ChangeDetectionStrategy.Default` where `OnPush` would suffice; subscriptions without `takeUntil`/`async pipe` that accumulate listeners. - - **Svelte:** `$:` blocks with expensive logic that re-runs more than needed. - - **Vanilla:** `scroll`/`resize` listeners without `passive: true` or debounce; DOM manipulation inside a loop that forces repeated reflow. - -### 4. Network - -- Are static assets cached with long `max-age` + content hashing? -- Is HTTP/2 or HTTP/3 enabled? -- Are there unnecessary redirects? -- Are API responses paginated? Any `SELECT *` or unbounded fetch patterns? -- Are bulk operations used instead of loops of individual API calls? -- Is response compression enabled (gzip/brotli)? -- **AI-generated patterns:** - - Over-fetching data "just in case." - - Sequential `await`s when `Promise.all` (or parallel `fetch`) would work. - - Redundant API calls where one would suffice; missing deduplication on parallel requests. - -## Severity Classification - -| Severity | Criteria | Action | -|----------|----------|--------| -| **Critical** | Directly causes a Core Web Vital to fail the "Good" threshold | Fix before release | -| **High** | Likely degrades a CWV or causes significant loading/interaction slowdown | Fix before release | -| **Medium** | Suboptimal pattern with measurable but contained impact | Fix in current sprint | -| **Low** | Best practice gap with minor or speculative impact | Schedule for next sprint | -| **Info** | Improvement opportunity with no current evidence of impact | Consider adopting | - -## Output Format - -```markdown -## Web Performance Audit - -### Scorecard - -| Metric | Value | Source | Target | Status | -|--------|-------|--------|--------|--------| -| LCP | [value or "not measured"] | [Field (CrUX) / Lab (Lighthouse) / Trace (DevTools) / —] | ≤ 2.5s | [Good / Needs Work / Poor / —] | -| INP | [value or "not measured"] | [Field (CrUX) / Lab (Lighthouse) / Trace (DevTools) / —] | ≤ 200ms | [Good / Needs Work / Poor / —] | -| CLS | [value or "not measured"] | [Field (CrUX) / Lab (Lighthouse) / Trace (DevTools) / —] | ≤ 0.1 | [Good / Needs Work / Poor / —] | -| Lighthouse Performance | [score or "not measured"] | [Lab (Lighthouse) / —] | ≥ 90 | [Pass / Fail / —] | - -> Artifacts used: [list each: Lighthouse report `path/file.json`, CrUX API response, DevTools trace, live MCP capture, or **none — source analysis only**] -> Framework / stack detected: [Next.js 14 App Router / React 18 + Vite / vanilla HTML / etc.] - -### Summary -- Critical: [count] -- High: [count] -- Medium: [count] -- Low: [count] - -### Findings - -#### [CRITICAL] [Finding title] -- **Area:** Core Web Vitals / Loading / Rendering / Network -- **Location:** [file:line or component, or URL when from live capture] -- **Description:** [What the issue is] -- **Impact:** [potential impact / measured: e.g. "+1.2s LCP regression on mobile p75"] -- **Recommendation:** [Specific fix with a small code example when applicable] - -#### [HIGH] [Finding title] -... - -### Positive Observations -- [Performance practices done well] - -### Recommendations -- [Proactive improvements to consider] -``` - -## Rules - -1. Lead with the scorecard. If not measured, say so explicitly before listing findings. -2. Always label scorecard values with their source. Never present lab values as field values or vice versa. -3. Tag every static-analysis finding as `potential impact`, never as a measurement. -4. Identify the framework / stack before recommending framework-specific patterns. Do not recommend idioms from a stack the project does not use. -5. Every finding must include a specific, actionable recommendation. -6. Do not recommend micro-optimizations without evidence they affect a Core Web Vital or another measurable metric. -7. Acknowledge good performance practices — positive reinforcement matters. -8. Use `references/performance-checklist.md` as the minimum baseline for each area. -9. Delegate granular optimization guidance and remediation steps to `skills/performance-optimization/SKILL.md` — keep this report at the audit level. -10. Fold AI-generated anti-patterns into their relevant area (Network or Rendering/JS); do not create a separate "AI" category. -11. In Deep mode, always state which artifacts were provided and which fields remain unmeasured. - -## Composition - -- **Invoke directly when:** the user wants a performance-focused pass on a web application, a specific component, a route, or a live URL. -- **Invoke via:** `/webperf` (dedicated performance audit command). Not included in `/ship` fan-out — performance audits apply to web applications only, not to utility libraries or CLI tools, so adding it to a global pre-launch fan-out would create noise in non-web projects. -- **Do not invoke from another persona.** If `code-reviewer` flags a performance concern that warrants a deeper pass, surface that recommendation in the report; the user or a slash command initiates the deeper pass. See [docs/agents.md](../docs/agents.md). diff --git a/spec/agent-skills/commands/build.toml b/spec/agent-skills/commands/build.toml deleted file mode 100644 index b7a4f7f1..00000000 --- a/spec/agent-skills/commands/build.toml +++ /dev/null @@ -1,43 +0,0 @@ -description = "Implement tasks incrementally — build, test, verify, commit. Add \"auto\" to run the whole plan in one approved pass." - -prompt = """ -Invoke the incremental-implementation skill alongside test-driven-development. - -## Modes - -- `/build` — implement the next pending task, then stop (careful, one slice at a time). -- `/build auto` — generate the plan if needed, get a single approval, then implement every task without stopping between them. - -The arguments select the mode. Treat `auto` (canonical) or `all` as autonomous mode; anything else (or empty) is the default single-task mode. Note: autonomous mode is not faster per task — it runs the same test-driven loop — it only removes the human stepping between tasks. - -## Default: one task - -Pick the next pending task from the plan. Then: - -1. Read the task's acceptance criteria -2. Load relevant context (existing code, patterns, types) -3. Write a failing test for the expected behavior (RED) -4. Implement the minimum code to pass the test (GREEN) -5. Run the full test suite to check for regressions -6. Run the build to verify compilation -7. Commit with a descriptive message -8. Mark the task complete and stop - -## Autonomous: the whole plan (`/build auto`) - -Use this once a spec exists and you want to collapse plan + build into one run. It removes the manual stepping between tasks — not the verification. Every task still earns a passing test and its own commit. - -1. Require a spec. Look only for a spec at a known path: SPEC.md at the repo root, docs/SPEC.md, or a file under spec/. A README or arbitrary doc does NOT count. If none exists, stop and tell the user to run /spec first — do not invent requirements. -2. Establish a clean baseline. Run `git status --porcelain`. If there are uncommitted changes outside the expected planning artifacts (SPEC.md, docs/SPEC.md, spec/*, tasks/plan.md, tasks/todo.md), stop and ask the user to commit, stash, or confirm how to handle them. Autonomous per-task commits must not absorb unrelated local work, or the clean-rollback guarantee breaks. -3. Plan if needed. If there is no tasks/plan.md, invoke the planning-and-task-breakdown skill to generate one. -4. Single checkpoint. Present the full plan and wait for an unambiguous affirmative (e.g. "approve", "go", "yes"). Treat hedged responses ("looks reasonable", "I guess") as NOT approved. This is the only human gate — after approval, run autonomously. If you generated tasks/plan.md, commit it as a single preparatory commit now so it doesn't bleed into the first task's commit. -5. Execute every task in dependency order. Use each task's declared dependencies; if they aren't explicit, execute in the order the plan lists them. For each task, run the full default loop above (RED → GREEN → regression → build → commit → mark complete). Stage only the files that task touched plus its task-status update — never `git add -A` blindly — and make one commit per task so any point is a clean rollback. -6. Stop and ask the user (do not push through) when: - - a test can't be made to pass or the build breaks without an obvious fix → follow the debugging-and-error-recovery skill - - the spec is ambiguous, or a task needs a decision the spec doesn't cover - - a task is high-risk or irreversible — auth/permission changes, destructive data migrations, payments, deletions, deploys, anything touching secrets, or anything you can't undo with `git revert` → follow the doubt-driven-development skill and get explicit sign-off before continuing - After the user resolves a blocker, they re-invoke /build auto — it resumes from the next pending task. -7. Summarize at the end: tasks completed, tests added, commits made, and anything skipped, flagged, or left for the user. - -If any step fails, follow the debugging-and-error-recovery skill. -""" diff --git a/spec/agent-skills/commands/code-simplify.toml b/spec/agent-skills/commands/code-simplify.toml deleted file mode 100644 index 926442b9..00000000 --- a/spec/agent-skills/commands/code-simplify.toml +++ /dev/null @@ -1,22 +0,0 @@ -description = "Simplify code for clarity and maintainability — reduce complexity without changing behavior" - -prompt = """ -Invoke the code-simplification skill. - -Simplify recently changed code (or the specified scope) while preserving exact behavior: - -1. Read AGENTS.md and study project conventions -2. Identify the target code — recent changes unless a broader scope is specified -3. Understand the code's purpose, callers, edge cases, and test coverage before touching it -4. Scan for simplification opportunities: - - Deep nesting → guard clauses or extracted helpers - - Long functions → split by responsibility - - Nested ternaries → if/else or switch - - Generic names → descriptive names - - Duplicated logic → shared functions - - Dead code → remove after confirming -5. Apply each simplification incrementally — run tests after each change -6. Verify all tests pass, the build succeeds, and the diff is clean - -If tests fail after a simplification, revert that change and reconsider. Use `code-review-and-quality` to review the result. -""" \ No newline at end of file diff --git a/spec/agent-skills/commands/planning.toml b/spec/agent-skills/commands/planning.toml deleted file mode 100644 index 3b8daa23..00000000 --- a/spec/agent-skills/commands/planning.toml +++ /dev/null @@ -1,16 +0,0 @@ -description = "Break work into small verifiable tasks with acceptance criteria and dependency ordering" - -prompt = """ -Invoke the planning-and-task-breakdown skill. - -Read the existing spec (SPEC.md or equivalent) and the relevant codebase sections. Then: - -1. Enter plan mode — read only, no code changes -2. Identify the dependency graph between components -3. Slice work vertically (one complete path per task, not horizontal layers) -4. Write tasks with acceptance criteria and verification steps -5. Add checkpoints between phases -6. Present the plan for human review - -Save the plan to tasks/plan.md and task list to tasks/todo.md. -""" \ No newline at end of file diff --git a/spec/agent-skills/commands/review.toml b/spec/agent-skills/commands/review.toml deleted file mode 100644 index 23f5b78c..00000000 --- a/spec/agent-skills/commands/review.toml +++ /dev/null @@ -1,16 +0,0 @@ -description = "Conduct a five-axis code review — correctness, readability, architecture, security, performance" - -prompt = """ -Invoke the code-review-and-quality skill. - -Review the current changes (staged or recent commits) across all five axes: - -1. **Correctness** — Does it match the spec? Edge cases handled? Tests adequate? -2. **Readability** — Clear names? Straightforward logic? Well-organized? -3. **Architecture** — Follows existing patterns? Clean boundaries? Right abstraction level? -4. **Security** — Input validated? Secrets safe? Auth checked? (Use security-and-hardening skill) -5. **Performance** — No N+1 queries? No unbounded ops? (Use performance-optimization skill) - -Categorize findings as Critical, Important, or Suggestion. -Output a structured review with specific file:line references and fix recommendations. -""" \ No newline at end of file diff --git a/spec/agent-skills/commands/ship.toml b/spec/agent-skills/commands/ship.toml deleted file mode 100644 index bf0a7764..00000000 --- a/spec/agent-skills/commands/ship.toml +++ /dev/null @@ -1,72 +0,0 @@ -description = "Run the pre-launch checklist via parallel fan-out to specialist personas, then synthesize a go/no-go decision" - -prompt = """ -Invoke the shipping-and-launch skill. - -`/ship` is a **fan-out orchestrator**. It runs three specialist personas in parallel against the current change, then merges their reports into a single go/no-go decision with a rollback plan. The personas operate independently — no shared state, no ordering — which is what makes parallel execution safe and useful here. - -## Phase A — Parallel fan-out - -Spawn three subagents concurrently. The CLI exposes each custom subagent in `agents/` as a tool with the same name — so `code-reviewer.md` becomes a `code-reviewer` tool the main agent can call, and `@code-reviewer` works as an explicit invocation in the prompt. **Issue all three subagent tool calls in a single assistant turn so they execute in parallel** — sequential calls defeat the purpose of this command. - -Dispatch each persona by tool name: - -1. **`code-reviewer`** — Run a five-axis review (correctness, readability, architecture, security, performance) on the staged changes or recent commits. Output the standard review template. -2. **`security-auditor`** — Run a vulnerability and threat-model pass. Check OWASP Top 10, secrets handling, auth/authz, dependency CVEs. Output the standard audit report. -3. **`test-engineer`** — Analyze test coverage for the change. Identify gaps in happy path, edge cases, error paths, and concurrency scenarios. Output the standard coverage analysis. - -If subagents are unavailable in the current CLI version, invoke each persona's system prompt sequentially in the main context and treat their outputs as if returned in parallel — the merge phase still works. - -Constraints (from CLI's subagent model): -- Subagents run in isolated context loops and return only their report to this main session. -- Do not let one persona delegate to another — keep the fan-out flat. -- For richer multi-agent collaboration where teammates talk to each other instead of just reporting back, see `references/orchestration-patterns.md`. - -**Persona resolution.** If you've defined your own `code-reviewer`, `security-auditor`, or `test-engineer` in `agents/` or your global configuration, those take precedence over this plugin's versions — `/ship` picks up your customizations automatically. This is intentional: plugin subagents sit at the bottom of the CLI's scope priority table, so user-level definitions win by design. - -## Phase B — Merge in main context - -Once all three reports are back, the main agent (not a sub-persona) synthesizes them: - -1. **Code Quality** — Aggregate Critical/Important findings from `code-reviewer` and any failing tests, lint, or build output. Resolve duplicates between reviewers. -2. **Security** — Promote any Critical/High `security-auditor` findings to launch blockers. Cross-reference with `code-reviewer`'s security axis. -3. **Performance** — Pull from `code-reviewer`'s performance axis; cross-check Core Web Vitals if applicable. -4. **Accessibility** — Verify keyboard nav, screen reader support, contrast (not covered by the three personas — handle directly here, or invoke the accessibility checklist). -5. **Infrastructure** — Env vars, migrations, monitoring, feature flags. Verify directly. -6. **Documentation** — README, ADRs, changelog. Verify directly. - -## Phase C — Decision and rollback - -Produce a single output: - -```markdown -## Ship Decision: GO | NO-GO - -### Blockers (must fix before ship) -- [Source persona: Critical finding + file:line] - -### Recommended fixes (should fix before ship) -- [Source persona: Important finding + file:line] - -### Acknowledged risks (shipping anyway) -- [Risk + mitigation] - -### Rollback plan -- Trigger conditions: [what signals would prompt rollback] -- Rollback procedure: [exact steps] -- Recovery time objective: [target] - -### Specialist reports (full) -- [code-reviewer report] -- [security-auditor report] -- [test-engineer report] -``` - -## Rules - -1. The three Phase A personas run in parallel — never sequentially. -2. Personas do not call each other. The main agent merges in Phase B. -3. The rollback plan is mandatory before any GO decision. -4. If any persona returns a Critical finding, the default verdict is NO-GO unless the user explicitly accepts the risk. -5. **Skip the fan-out only if all of the following are true:** the change touches 2 files or fewer, the diff is under 50 lines, and it does not touch auth, payments, data access, or config/env. Otherwise, default to fan-out. `/ship` is designed for production-bound changes — when the blast radius is non-trivial, run the parallel review even if the diff looks small. -""" \ No newline at end of file diff --git a/spec/agent-skills/commands/spec.md b/spec/agent-skills/commands/spec.md deleted file mode 100644 index 22079353..00000000 --- a/spec/agent-skills/commands/spec.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -description: Start spec-driven development — write a structured specification before writing code ---- - -Invoke the agent-skills:spec-driven-development skill. - -Begin by understanding what the user wants to build. Ask clarifying questions about: -1. The objective and target users -2. Core features and acceptance criteria -3. Tech stack preferences and constraints -4. Known boundaries (what to always do, ask first about, and never do) - -Then generate a structured spec covering all six core areas: objective, commands, project structure, code style, testing strategy, and boundaries. - -Save the spec as SPEC.md in the project root and confirm with the user before proceeding. diff --git a/spec/agent-skills/commands/spec.toml b/spec/agent-skills/commands/spec.toml deleted file mode 100644 index 02b8896c..00000000 --- a/spec/agent-skills/commands/spec.toml +++ /dev/null @@ -1,15 +0,0 @@ -description = "Start spec-driven development — write a structured specification before writing code" - -prompt = """ -Invoke the spec-driven-development skill. - -Begin by understanding what the user wants to build. Ask clarifying questions about: -1. The objective and target users -2. Core features and acceptance criteria -3. Tech stack preferences and constraints -4. Known boundaries (what to always do, ask first about, and never do) - -Then generate a structured spec covering all six core areas: objective, commands, project structure, code style, testing strategy, and boundaries. - -Save the spec as SPEC.md in the project root and confirm with the user before proceeding. -""" \ No newline at end of file diff --git a/spec/agent-skills/commands/test.toml b/spec/agent-skills/commands/test.toml deleted file mode 100644 index 73e36f53..00000000 --- a/spec/agent-skills/commands/test.toml +++ /dev/null @@ -1,19 +0,0 @@ -description = "Run TDD workflow — write failing tests, implement, verify. For bugs, use the Prove-It pattern." - -prompt = """ -Invoke the test-driven-development skill. - -For new features: -1. Write tests that describe the expected behavior (they should FAIL) -2. Implement the code to make them pass -3. Refactor while keeping tests green - -For bug fixes (Prove-It pattern): -1. Write a test that reproduces the bug (must FAIL) -2. Confirm the test fails -3. Implement the fix -4. Confirm the test passes -5. Run the full test suite for regressions - -For browser-related issues, also invoke browser-testing-with-devtools to verify with Chrome DevTools MCP. -""" \ No newline at end of file diff --git a/spec/agent-skills/commands/webperf.toml b/spec/agent-skills/commands/webperf.toml deleted file mode 100644 index 62b11bcd..00000000 --- a/spec/agent-skills/commands/webperf.toml +++ /dev/null @@ -1,32 +0,0 @@ -description = "Run a web performance audit via the web-performance-auditor persona" - -prompt = """ -/webperf targets web applications specifically. Do not use it for utility libraries, CLIs, or server-only code with no browser-facing output. - -## Determine the mode - -Deep mode — activate when any of these is available: -- A Lighthouse JSON report file (e.g. `npx lighthouse --output json --output-path ./report.json`, or `npx -p chrome-devtools-mcp chrome-devtools lighthouse_audit --output-format=json` from the Chrome DevTools MCP CLI) -- A PageSpeed Insights JSON response (includes Lighthouse + CrUX) -- A CrUX API response (requires CRUX_API_KEY or GOOGLE_API_KEY) -- A DevTools performance trace -- A live URL plus the chrome-devtools MCP server configured in the harness (capture metrics directly via lighthouse_audit and performance_* tools) -- The Chrome DevTools MCP CLI invoked locally (via `npx -p chrome-devtools-mcp chrome-devtools `), passing the JSON output to the agent - -Quick mode — default when none of the above are available. Scan source code for structural anti-patterns and label every finding as `potential impact`. - -## Run the audit - -Spawn the `web-performance-auditor` subagent (the CLI exposes each custom subagent in `agents/` as a tool with the same name). Pass it explicitly: - -- The files, components, or diff under review -- Any artifact paths (Lighthouse JSON, PSI JSON, CrUX response, trace) or pasted JSON content -- The target URL or page name when known -- A note on which mode you expect (Quick or Deep), so the agent surfaces missing inputs if Deep was intended - -The subagent returns a scorecard (only populated with sourced values — mark unmeasured fields `not measured`, never fabricate metrics), a ranked list of findings, positive observations, and proactive recommendations. - -## Output - -Return the full audit report to the user. No synthesis or merge step is needed — this is a single-persona command. -""" diff --git a/spec/agent-skills/definition-of-done.md b/spec/agent-skills/definition-of-done.md deleted file mode 100644 index 35e39f9e..00000000 --- a/spec/agent-skills/definition-of-done.md +++ /dev/null @@ -1,67 +0,0 @@ -# Definition of Done - -A standing, project-wide bar that every change must clear before it counts as done. Unlike acceptance criteria, which vary per task and answer "did we build the right thing?", the Definition of Done is the same every time and answers "is this finished to our standard?". Use it as the final gate in `planning-and-task-breakdown`, `incremental-implementation`, and `shipping-and-launch`. - -## Definition of Done vs. Acceptance Criteria - -| | Acceptance Criteria | Definition of Done | -|---|---|---| -| Scope | Specific to one task or spec | Applies to every increment | -| Changes | Different for each item | Fixed and reused | -| Answers | "Did we build *this thing*?" | "Is it *ready*?" | -| Owner | Defined when planning the task | Defined once for the project | -| Example | "User can reset password via email link" | "Tests pass, no regressions, docs updated" | - -The two are complementary. A task is done only when **its** acceptance criteria are met **and** the standing Definition of Done is satisfied. Skipping either leaves work that looks finished but is not. - -## The Standing Checklist - -Apply this to every change before declaring it done. - -### Correctness -- [ ] All acceptance criteria for the task are met -- [ ] Code runs and behaves as intended, verified at runtime, not just compiled or typechecked -- [ ] New behavior is covered by tests that fail without the change and pass with it -- [ ] Existing tests still pass; no regressions introduced -- [ ] Edge cases and error paths are handled, not just the happy path - -### Quality -- [ ] Code reveals intent through naming and structure; no comments needed to explain *what* it does -- [ ] No duplicated business logic -- [ ] No dead code, debug output, or commented-out blocks left behind -- [ ] Changes are scoped to the task; no unrelated refactors snuck in -- [ ] Linting and formatting pass - -The depth behind these items lives in `code-review-and-quality` (the five-axis review) and `code-simplification` (reducing complexity without changing behavior). - -### Integration -- [ ] Change works with the rest of the system, not just in isolation -- [ ] Database migrations, config changes, and feature flags are accounted for -- [ ] Backward compatibility considered for any public interface or API change - -### Documentation -- [ ] Public interfaces, APIs, and user-facing behavior are documented -- [ ] Architectural decisions worth preserving are recorded (see `documentation-and-adrs`) -- [ ] Documentation describes the current state in timeless language, not the change history - -### Ship-readiness -- [ ] Security implications reviewed for any untrusted input, auth, or data handling (see `security-and-hardening`) -- [ ] Observability in place for new critical paths (logs, metrics, traces) (see `observability-and-instrumentation`) -- [ ] Rollback path exists for anything risky (see `shipping-and-launch`) -- [ ] The human has reviewed and approved before merge or deploy - -## How to Apply - -- **Per task**: confirm the Correctness and Quality sections before checking the task off. -- **Per feature**: confirm Integration and Documentation before considering the feature complete. -- **Per release**: the full checklist is the floor; `shipping-and-launch` adds the deploy-specific gates on top. - -Tailor the list to the project once, then reuse it unchanged. A Definition of Done that is renegotiated every sprint is not a Definition of Done. - -## Red Flags - -- "It's done, I just haven't run it yet": unverified work is not done. -- "Tests pass" used as a synonym for done while docs, regressions, or runtime verification are skipped. -- A different bar applied depending on deadline pressure. -- Acceptance criteria treated as the whole bar, with no standing quality floor. -- "Done" declared before human review on changes that need it. diff --git a/spec/agent-skills/docs/agents.md b/spec/agent-skills/docs/agents.md deleted file mode 100644 index 414177ba..00000000 --- a/spec/agent-skills/docs/agents.md +++ /dev/null @@ -1,123 +0,0 @@ -# Agent Personas - -Specialist personas that play a single role with a single perspective. Each persona is a Markdown file consumed as a system prompt by your harness (Claude Code, Cursor, Copilot, etc.). - -| Persona | Role | Best for | -|---------|------|----------| -| [code-reviewer](../agents/code-reviewer.md) | Senior Staff Engineer | Five-axis review before merge | -| [security-auditor](../agents/security-auditor.md) | Security Engineer | Vulnerability detection, OWASP-style audit | -| [test-engineer](../agents/test-engineer.md) | QA Engineer | Test strategy, coverage analysis, Prove-It pattern | -| [web-performance-auditor](../agents/web-performance-auditor.md) | Web Performance Engineer | Core Web Vitals audit, loading/rendering/network analysis | - -## How personas relate to skills and commands - -Three layers, each with a distinct job: - -| Layer | What it is | Example | Composition role | -|-------|-----------|---------|------------------| -| **Skill** | A workflow with steps and exit criteria | `code-review-and-quality` | The *how* — invoked from inside a persona or command | -| **Persona** | A role with a perspective and an output format | `code-reviewer` | The *who* — adopts a viewpoint, produces a report | -| **Command** | A user-facing entry point | `/review`, `/ship` | The *when* — composes personas and skills | - -The user (or a slash command) is the orchestrator. **Personas do not call other personas.** Skills are mandatory hops inside a persona's workflow. - -## When to use each - -### Direct persona invocation -Pick this when you want one perspective on the current change and the user is in the loop. - -- "Review this PR" → invoke `code-reviewer` directly -- "Are there security issues in `auth.ts`?" → invoke `security-auditor` directly -- "What tests are missing for the checkout flow?" → invoke `test-engineer` directly -- "Audit Core Web Vitals on the product page" → invoke `web-performance-auditor` directly - -### Slash command (single persona behind it) -Pick this when there's a repeatable workflow you'd otherwise re-explain every time. - -- `/review` → wraps `code-reviewer` with the project's review skill -- `/test` → wraps `test-engineer` with TDD skill -- `/webperf` → wraps `web-performance-auditor` for performance-focused audits on web apps - -### Slash command (orchestrator — fan-out) -Pick this only when **independent** investigations can run in parallel and produce reports that a single agent then merges. - -- `/ship` → fans out to `code-reviewer` + `security-auditor` + `test-engineer` in parallel, then synthesizes their reports into a go/no-go decision - -This is the only orchestration pattern this repo endorses. See [references/orchestration-patterns.md](../references/orchestration-patterns.md) for the full pattern catalog and anti-patterns. - -## Decision matrix - -``` -Is the work a single perspective on a single artifact? -├── Yes → Direct persona invocation -└── No → Are the sub-tasks independent (no shared mutable state, no ordering)? - ├── Yes → Slash command with parallel fan-out (e.g. /ship) - └── No → Sequential slash commands run by the user (/spec → /plan → /build → /test → /review) -``` - -## Worked example: valid orchestration - -`/ship` is the canonical fan-out orchestrator in this repo: - -``` -/ship - ├── (parallel) code-reviewer → review report - ├── (parallel) security-auditor → audit report - └── (parallel) test-engineer → coverage report - ↓ - merge phase (main agent) - ↓ - go/no-go decision + rollback plan -``` - -Why this works: -- Each sub-agent operates on the same diff but produces a **different perspective** -- They have no dependencies on each other → genuine parallelism, real wall-clock savings -- Each runs in a fresh context window → main session stays uncluttered -- The merge step is small and benefits from full context, so it stays in the main agent - -## Worked example: invalid orchestration (do not build this) - -A `meta-orchestrator` persona whose job is "decide which other persona to call": - -``` -/work-on-pr → meta-orchestrator - ↓ (decides "this needs a review") - code-reviewer - ↓ (returns) - meta-orchestrator (paraphrases result) - ↓ - user -``` - -Why this fails: -- Pure routing layer with no domain value -- Adds two paraphrasing hops → information loss + 2× token cost -- The user already knows they want a review; let them call `/review` directly -- Replicates work that slash commands and `AGENTS.md` intent-mapping already do - -## Rules for personas - -1. A persona is a single role with a single output format. If you find yourself adding a second role, create a second persona. -2. **Personas do not invoke other personas.** Composition is the job of slash commands or the user. On Claude Code this is also a hard platform constraint — *"subagents cannot spawn other subagents"* — so the rule is enforced for you. -3. A persona may invoke skills (the *how*). -4. Every persona file ends with a "Composition" block stating where it fits. - -## Claude Code interop - -The personas in this repo are designed to work as Claude Code subagents and as Agent Teams teammates without modification: - -- **As subagents:** auto-discovered when this plugin is enabled (no path config needed). Use the Agent tool with `subagent_type: code-reviewer` (or `security-auditor`, `test-engineer`). `/ship` is the canonical example. -- **As Agent Teams teammates** (experimental, requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`): reference the same persona name when spawning a teammate. The persona's body is **appended to** the teammate's system prompt as additional instructions (not a replacement), so your persona text sits on top of the team-coordination instructions the lead installs (SendMessage, task-list tools, etc.). - -Subagents only report results back to the main agent. Agent Teams let teammates message each other directly. Use subagents when reports are enough; use Agent Teams when sub-agents need to challenge each other's findings (e.g. competing-hypothesis debugging). See [references/orchestration-patterns.md](../references/orchestration-patterns.md) for the full mapping. - -Plugin agents do not support `hooks`, `mcpServers`, or `permissionMode` frontmatter — those fields are silently ignored. Avoid relying on them when authoring new personas here. - -## Adding a new persona - -1. Create `agents/.md` with the same frontmatter format used by existing personas. -2. Define the role, scope, output format, and rules. -3. Add a **Composition** block at the bottom (Invoke directly when / Invoke via / Do not invoke from another persona). -4. Add the persona to the table at the top of this file. -5. If the persona enables a new orchestration pattern, document it in `references/orchestration-patterns.md` rather than inventing the pattern in the persona file itself. diff --git a/spec/agent-skills/docs/antigravity-setup.md b/spec/agent-skills/docs/antigravity-setup.md deleted file mode 100644 index 018bd3a3..00000000 --- a/spec/agent-skills/docs/antigravity-setup.md +++ /dev/null @@ -1,123 +0,0 @@ -# Using agent-skills with Antigravity CLI (agy) - -The `agent-skills` package can be installed as a native plugin in the Antigravity CLI (`agy`), giving the agent access to structured workflows, personas, and custom slash commands. - -## Setup - -### Option 1: Native Plugin Installation (Recommended) - -Antigravity CLI has a first-class plugin system that registers skills, agents, and custom commands. - -**Install from the remote repository:** - -```bash -agy plugin install https://github.com/addyosmani/agent-skills.git -``` - -**Install from a local clone:** - -1. Clone the repository: - ```bash - git clone https://github.com/addyosmani/agent-skills.git - ``` -2. Install the plugin using `agy`: - ```bash - agy plugin install /path/to/agent-skills - ``` - -This will validate the plugin and install it into your global Antigravity configuration directory (`~/.gemini/antigravity-cli/plugins/agent-skills/`). - -### Option 2: Import from Gemini CLI - -If you have already installed `agent-skills` under your legacy Gemini CLI installation, you can import it directly: -```bash -agy plugin import gemini -``` - -Once installed, verify the active plugin: -```bash -agy plugin list -``` - ---- - -## Slash Commands - -The plugin registers 8 custom slash commands: 7 lifecycle commands plus the `/webperf` specialist audit: - -| Command | What it does | Activated Skill | -|---------|--------------|-----------------| -| `/spec` | Write a structured spec before writing code | `spec-driven-development` | -| `/planning` | Break work into small, verifiable tasks | `planning-and-task-breakdown` | -| `/build` | Implement the next task incrementally | `incremental-implementation` | -| `/test` | Run TDD workflow — red, green, refactor | `test-driven-development` | -| `/review` | Five-axis code review | `code-review-and-quality` | -| `/code-simplify` | Reduce complexity without changing behavior | `code-simplification` | -| `/ship` | Pre-launch checklist via parallel persona fan-out | `shipping-and-launch` | -| `/webperf` | Audit browser-facing apps for Core Web Vitals and performance issues | `web-performance-auditor` | - -Each command automatically invokes the corresponding skill and guides the agent step-by-step. - -> **Note:** Use `/planning` instead of `/plan` to avoid conflicts with Antigravity's internal plan-generation command. - ---- - -## Skills & Discovery - -Antigravity automatically discovers skills inside the plugin's `skills/` directory. -* Antigravity matches user tasks and intents to relevant skills on-demand. -* If a task matches a skill, the agent will load the skill and prompt you for permission before executing. - ---- - -## Verification & Validation - -To validate that your local plugin is correctly structured and contains all skills, run: -```bash -agy plugin validate /path/to/agent-skills -``` - ---- - -## How It Works - -### 1. On-Demand Skill Activation -Antigravity CLI automatically discovers the `SKILL.md` files located in the `skills/` directory of the installed plugin. Using the trigger descriptions in each skill's frontmatter, the agent will dynamically activate the appropriate workflow when it detects matching developer intent. - -For example, when you ask the agent to: -* **Design a new system** → It will suggest/activate `spec-driven-development`. -* **Implement a feature** → It will activate `incremental-implementation` and `test-driven-development`. -* **Fix a bug** → It will activate `debugging-and-error-recovery`. - -### 2. Specialized Agent Personas -The plugin registers reusable subagent definitions from the `agents/` directory: -\* `code-reviewer.md` -\* `security-auditor.md` -\* `test-engineer.md` - -You can invoke these personas directly within your session or when delegating tasks using subagents. - ---- - -## Configuration & Customization - -### Project-Specific Enforcements (`AGENTS.md`) -To enforce strict skill compliance (e.g. requiring a spec or plan before writing code), copy or link `AGENTS.md` into the root of your workspace. Antigravity CLI reads this file to align the agent's behavior and planning phase with your team's conventions. - -### Sandbox Mode -If you want to run skills or scripts with limited terminal permissions (for safety when running third-party validation tests), launch the CLI with: - -```bash -agy --sandbox -``` - ---- - -## Usage Tips - -1. **Keep plugins up-to-date:** You can update the CLI or check for newer plugin versions using: - ```bash - agy update - ``` -2. **Review before execution:** When agents execute complex refactoring tasks using these skills, use `Ctrl+r` to enter the **Artifact Review** screen to review, edit, or approve code before it is committed. -3. **Control permissions:** You can use the `--dangerously-skip-permissions` flag only in trusted local projects where you want to bypass manual tool approval prompts. diff --git a/spec/agent-skills/docs/comparison.md b/spec/agent-skills/docs/comparison.md deleted file mode 100644 index ff6a77a8..00000000 --- a/spec/agent-skills/docs/comparison.md +++ /dev/null @@ -1,82 +0,0 @@ - - -# How agent-skills compares - -People often ask how **agent-skills** relates to two other popular "skills for coding agents" collections: **Superpowers** (by Jesse Vincent / obra) and **Matt Pocock's skills**. All three are good, share a lot of DNA, and are worth learning from. This page is an honest map of how they're *shaped* differently so you can pick the one that fits how you work - or borrow from more than one. - -> **TL;DR** - They optimize for different moments. **agent-skills** organizes the *whole product lifecycle* (Define → Plan → Build → Verify → Review → Ship) with review personas and anti-rationalization guards. **Superpowers** leans into *autonomous, reasoning-heavy* runs with subagents and worktree isolation. **Matt Pocock's skills** are a *sharp, personal Claude Code toolkit* distilled from one expert's daily workflow. None of them is "best" in the abstract - it depends on the work in front of you. - ---- - -## At a glance - -| | **agent-skills** | **Superpowers** | **Matt Pocock's skills** | -|---|---|---|---| -| **Core idea** | Encode the full senior-engineering lifecycle as skills | A complete development *methodology* built on composable skills | One expert's `.claude` workflow, open-sourced | -| **Organizing principle** | SDLC **phases** (Define→Plan→Build→Verify→Review→Ship) with a meta-skill router | Disciplined execution loop (brainstorm → plan → execute) | A curated toolbox of focused commands | -| **Lifecycle coverage** | Broad - idea refinement, API/UI design, security, performance, CI/CD, deprecation, ADRs, launch | Deep on the core build loop (TDD, debugging, planning, review) | Planning + build + tooling + knowledge mgmt, opinionated | -| **Entry points** | Slash commands mapped 1:1 to phases (`/spec` `/plan` `/build` `/test` `/review` `/code-simplify` `/ship`, plus `/webperf`) | Commands like `/brainstorming`, `/execute-plan` | Slash commands like `/tdd`, `/grill-me`, `/diagnose`, `/grill-with-docs` | -| **Tooling reach** | Multi-tool: Claude Code, Cursor, Gemini CLI, Antigravity, OpenCode, Windsurf, Copilot | Multi-tool: Claude Code, Codex, Gemini CLI, OpenCode, Cursor, Copilot CLI, Factory Droid | Claude Code-first (also usable with Codex) | -| **Distinctive mechanisms** | Anti-rationalization tables + Red Flags in every skill; review **personas** with parallel fan-out in `/ship`; reference checklists | Subagent-driven development with two-stage review; git-worktree isolation; skills-that-write-skills | "Grill me" requirement interrogation; strict agent-level TDD; pre-commit/git guardrails | -| **Best for** | Driving a feature through every phase with a human checkpoint at each | Long, autonomous, reasoning-heavy or exploratory work | A pragmatic, battle-tested daily loop for TypeScript-style projects | - -*(Adoption numbers for these projects are cited wildly differently across blogs; we've left them out rather than repeat unverified figures.)* - ---- - -## The three projects, in their own terms - -### Superpowers - obra -A full software-development methodology built on composable skills. It bets on **autonomy and upfront reasoning**: Socratic brainstorming before code, fresh subagents that execute tasks and get a two-stage review (spec compliance, then code quality), and git worktrees so parallel work stays isolated. Its TDD discipline is strict - it will delete prematurely written code to hold the RED→GREEN→REFACTOR line. If you want to hand off a sizable chunk and come back to a reviewed result, this is the shape built for that. - -**Repo:** - -### Matt Pocock's skills - mattpocock -Matt open-sourced the actual `.claude` directory he uses day to day - a tight set of focused Claude Code skills. The standouts are `/tdd` (enforces red-green-refactor at the agent level) and `/grill-me` (interrogates your requirements before any code). It also covers PRD writing, issue breakdown, interface design, architecture passes, bug triage, pre-commit/git guardrails, and knowledge management. It's personal and opinionated in the best way: it reflects how one very good engineer actually ships, rather than trying to be an exhaustive framework. - -**Repo:** · related: - -### agent-skills - this project -agent-skills organizes the **entire product lifecycle** as skills, with a meta-skill (`using-agent-skills`) that routes a task to the right one. Every skill carries a **Common Rationalizations** table (the excuses an agent makes to skip a step, each rebutted) and **Red Flags**. Slash commands map one-to-one to lifecycle phases, and `/ship` fans out review **personas** - `code-reviewer`, `security-auditor`, `test-engineer`, `web-performance-auditor` - in parallel, then merges them into a go/no-go. It deliberately keeps a human checkpoint at each phase and runs across most major agent tools. - ---- - -## A real head-to-head: Superpowers vs. agent-skills - -Om Mishra ran a controlled experiment - same model (Sonnet 4.6), same repo, same prompt in Claude Code, only the skill framework changed - and wrote it up here: - -**["Superpowers vs Agent-Skills: Faster Shipping, Safer Reasoning"](https://www.linkedin.com/pulse/superpowers-vs-agent-skills-faster-shipping-safer-reasoning-om-mishra-dzakf/)** - Om Mishra - -His findings, summarized fairly: - -- **agent-skills** moved to code faster (~8 min vs ~12) and ran **more validation passes** (7 vs 5, including the full test suite). That broader validation caught a compatibility issue *outside* the immediate feature that the feature-specific tests missed. For that task, he gave the edge to agent-skills on **validation depth**. -- **Superpowers** invested more **upfront architectural reasoning**, which he still prefers as his daily driver for evolving production systems and exploratory work where there's no established pattern to follow. -- Token efficiency was effectively identical; both replanned once. - -It's one developer's single-task experiment, not a benchmark - but it's a useful, concrete illustration of the core trade-off: **broad disciplined validation vs. heavy upfront reasoning.** His own conclusion is the honest one: pick the tool to the task. - ---- - -## When to pick which - -- **Reach for agent-skills** when you want a **guided lifecycle** with a human checkpoint at each phase, parallel review/security/perf passes before merge, and coverage that extends past the build loop into security, performance, CI/CD, and launch. It also travels across the most agent tools. -- **Reach for Superpowers** when you want to **hand off long, autonomous stretches** and come back to a reviewed result, or when the work is exploratory/architectural and benefits from heavier upfront reasoning and subagent isolation. -- **Reach for Matt Pocock's skills** when you want a **sharp, low-ceremony daily toolkit** - especially the requirement-grilling and strict TDD loop - for a TypeScript-flavored Claude Code workflow. - -And you don't have to choose exclusively, but combine them with care. These are Markdown skills, not runtimes, so cherry-picking *individual* skills works well: pull in Matt's `grill-me`, Superpowers' subagent isolation, or a specific checklist alongside your main setup. - -What doesn't work is running two of them as your **active router at the same time**. Stacked meta-skills fight over command names (`/tdd` defined in two places), compete on routing logic, and pull in different TDD philosophies, so you get unpredictable behavior rather than the best of both. Pick one framework as your primary router, and borrow from the others à la carte. - ---- - -## Sources - -- Superpowers - -- Matt Pocock's skills - -- Om Mishra, *Superpowers vs Agent-Skills* - - -*Spotted something inaccurate about another project here? Open an issue or PR - we'd rather be fair than flattering.* diff --git a/spec/agent-skills/docs/copilot-setup.md b/spec/agent-skills/docs/copilot-setup.md deleted file mode 100644 index 01052280..00000000 --- a/spec/agent-skills/docs/copilot-setup.md +++ /dev/null @@ -1,87 +0,0 @@ -# Using agent-skills with GitHub Copilot - -## Setup - -### Copilot Instructions - -Copilot supports creating agent skills using a `.github/skills`, `.claude/skills`, or `.agents/skills` directory in your repository. - -```bash -mkdir -p .github - -# Create files for essential skills -cat /path/to/agent-skills/skills/test-driven-development/SKILL.md > .github/skills/test-driven-development/SKILL.md -cat /path/to/agent-skills/skills/code-review-and-quality/SKILL.md > .github/skills/code-review-and-quality/SKILL.md -``` - -For more details, refer [Creating agent skills for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-skills). - -### Agent Personas (*.agent.md) - -Copilot supports specialized agent personas. Use the agent-skills agents: - -> **Important:** GitHub Copilot requires custom agent files to be named `*.agent.md`. -> Files named `*.md` are silently ignored by Copilot. -> See [VS Code custom agents docs](https://code.visualstudio.com/docs/copilot/customization/custom-agents#_custom-agent-file-structure) for details. - -```bash -# Create the agents directory and copy agent definitions -mkdir -p .github/agents -cp /path/to/agent-skills/agents/code-reviewer.md .github/agents/code-reviewer.agent.md -cp /path/to/agent-skills/agents/test-engineer.md .github/agents/test-engineer.agent.md -cp /path/to/agent-skills/agents/security-auditor.md .github/agents/security-auditor.agent.md -``` - -Invoke agents in Copilot Chat: -- `@code-reviewer Review this PR` -- `@test-engineer Analyze test coverage for this module` -- `@security-auditor Check this endpoint for vulnerabilities` - -### Custom Instructions (User Level) - -For skills you want across all repositories: - -1. Open VS Code → Settings → GitHub Copilot → Custom Instructions -2. Add your most-used skill summaries - -## Recommended Configuration - -### .github/copilot-instructions.md - -GitHub Copilot supports project-level instructions via `.github/copilot-instructions.md`. - -```markdown -# Project Coding Standards - -## Testing -- Write tests before code (TDD) -- For bugs: write a failing test first, then fix (Prove-It pattern) -- Test hierarchy: unit > integration > e2e (use the lowest level that captures the behavior) -- Run `npm test` after every change - -## Code Quality -- Review across five axes: correctness, readability, architecture, security, performance -- Every PR must pass: lint, type check, tests, build -- No secrets in code or version control - -## Implementation -- Build in small, verifiable increments -- Each increment: implement → test → verify → commit -- Never mix formatting changes with behavior changes - -## Boundaries -- Always: Run tests before commits, validate user input -- Ask first: Database schema changes, new dependencies -- Never: Commit secrets, remove failing tests, skip verification -``` - -### Specialized Agents - -Use the agents for targeted review workflows in Copilot Chat. - -## Usage Tips - -1. **Keep instructions concise** — Copilot instructions work best when focused. Summarize the key rules rather than including full skill files. -2. **Use agents for review** — The code-reviewer, test-engineer, and security-auditor agents are designed for Copilot's agent model. -3. **Reference in chat** — When working on a specific phase, paste the relevant skill content into Copilot Chat for context. -4. **Combine with PR reviews** — Set up Copilot to review PRs using the code-reviewer agent persona. diff --git a/spec/agent-skills/docs/cursor-setup.md b/spec/agent-skills/docs/cursor-setup.md deleted file mode 100644 index 11ac905f..00000000 --- a/spec/agent-skills/docs/cursor-setup.md +++ /dev/null @@ -1,58 +0,0 @@ -# Using agent-skills with Cursor - -## Setup - -### Option 1: Rules Directory (Recommended) - -Cursor supports a `.cursor/rules/` directory for project-specific rules: - -```bash -# Create the rules directory -mkdir -p .cursor/rules - -# Copy skills you want as rules -cp /path/to/agent-skills/skills/test-driven-development/SKILL.md .cursor/rules/test-driven-development.md -cp /path/to/agent-skills/skills/code-review-and-quality/SKILL.md .cursor/rules/code-review-and-quality.md -cp /path/to/agent-skills/skills/incremental-implementation/SKILL.md .cursor/rules/incremental-implementation.md -``` - -Rules in this directory are automatically loaded into Cursor's context. - -### Option 2: .cursorrules File - -Create a `.cursorrules` file in your project root with the essential skills inlined: - -```bash -# Generate a combined rules file -cat /path/to/agent-skills/skills/test-driven-development/SKILL.md > .cursorrules -echo "\n---\n" >> .cursorrules -cat /path/to/agent-skills/skills/code-review-and-quality/SKILL.md >> .cursorrules -``` - -## Recommended Configuration - -### Essential Skills (Always Load) - -Add these to `.cursor/rules/`: - -1. `test-driven-development.md` — TDD workflow and Prove-It pattern -2. `code-review-and-quality.md` — Five-axis review -3. `incremental-implementation.md` — Build in small verifiable slices - -### Phase-Specific Skills (Load on Demand) - -For phase-specific work, create additional rule files as needed: - -- `spec-development.md` -> `spec-driven-development/SKILL.md` -- `frontend-ui.md` -> `frontend-ui-engineering/SKILL.md` -- `security.md` -> `security-and-hardening/SKILL.md` -- `performance.md` -> `performance-optimization/SKILL.md` - -Add these to `.cursor/rules/` when working on relevant tasks, then remove when done to manage context limits. - -## Usage Tips - -1. **Don't load all skills at once** - Cursor has context limits. Load 2-3 essential skills as rules and add phase-specific skills as needed. -2. **Reference skills explicitly** - Tell Cursor "Follow the test-driven-development rules for this change" to ensure it reads the loaded rules. -3. **Use agents for review** - Copy `agents/code-reviewer.md` content and tell Cursor to "review this diff using this code review framework." -4. **Load references on demand** - When working on performance, add `performance.md` to `.cursor/rules/` or paste the checklist content directly. diff --git a/spec/agent-skills/docs/gemini-cli-setup.md b/spec/agent-skills/docs/gemini-cli-setup.md deleted file mode 100644 index 7ad9d562..00000000 --- a/spec/agent-skills/docs/gemini-cli-setup.md +++ /dev/null @@ -1,132 +0,0 @@ -# Using agent-skills with Gemini CLI - -## Setup - -### Option 1: Install as Skills (Recommended) - -Gemini CLI has a native skills system that auto-discovers `SKILL.md` files in `.gemini/skills/` or `.agents/skills/` directories. Each skill activates on demand when it matches your task. - -**Install from the repo:** - -```bash -gemini skills install https://github.com/addyosmani/agent-skills.git --path skills -``` - -**Or install from a local clone:** - -```bash -git clone https://github.com/addyosmani/agent-skills.git -gemini skills install /path/to/agent-skills/skills/ -``` - -**Install for a specific workspace only:** - -```bash -gemini skills install /path/to/agent-skills/skills/ --scope workspace -``` - -Skills installed at workspace scope go into `.gemini/skills/` (or `.agents/skills/`). User-level skills go into `~/.gemini/skills/`. - -Once installed, verify with: - -``` -/skills list -``` - -Gemini CLI injects skill names and descriptions into the prompt automatically. When it recognizes a matching task, it asks permission to activate the skill before loading its full instructions. - -### Option 2: GEMINI.md (Persistent Context) - -For skills you want always loaded as persistent project context (rather than on-demand activation), add them to your project's `GEMINI.md`: - -```bash -# Create GEMINI.md with core skills as persistent context -cat /path/to/agent-skills/skills/incremental-implementation/SKILL.md > GEMINI.md -echo -e "\n---\n" >> GEMINI.md -cat /path/to/agent-skills/skills/code-review-and-quality/SKILL.md >> GEMINI.md -``` - -You can also modularize by importing from separate files: - -```markdown -# Project Instructions - -@skills/test-driven-development/SKILL.md -@skills/incremental-implementation/SKILL.md -``` - -Use `/memory show` to verify loaded context, and `/memory reload` to refresh after changes. - -> **Skills vs GEMINI.md:** Skills are on-demand expertise that activate only when relevant, keeping your context window clean. GEMINI.md provides persistent context loaded for every prompt. Use skills for phase-specific workflows and GEMINI.md for always-on project conventions. - -## Recommended Configuration - -### Always-On (GEMINI.md) - -Add these as persistent context for every session: - -- `incremental-implementation` — Build in small verifiable slices -- `code-review-and-quality` — Five-axis review - -### On-Demand (Skills) - -Install these as skills so they activate only when relevant: - -- `test-driven-development` — Activates when implementing logic or fixing bugs -- `spec-driven-development` — Activates when starting a new project or feature -- `frontend-ui-engineering` — Activates when building UI -- `security-and-hardening` — Activates during security reviews -- `performance-optimization` — Activates during performance work - -## Advanced Configuration - -### MCP Integration - -Many skills in this pack leverage [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) tools to interact with the environment. For example: - -- `browser-testing-with-devtools` uses the `chrome-devtools` MCP extension. -- `performance-optimization` can benefit from performance-related MCP tools. - -To enable these, ensure you have the relevant MCP extensions installed in your Gemini CLI configuration (`~/.gemini/config.json`). - -### Session Hooks - -Gemini CLI supports session lifecycle hooks. You can use these to automatically inject context or run validation scripts at the start of a session. - -To replicate the `agent-skills` experience from other tools, you can configure a `SessionStart` hook that reminds you of the available skills or loads a meta-skill. - -### Explicit Context Loading - -You can explicitly load any skill into your current session by referencing it with the `@` symbol in your prompt: - -```markdown -Use the @skills/test-driven-development/SKILL.md skill to implement this fix. -``` - -This is useful when you want to ensure a specific workflow is followed without waiting for auto-discovery. - -## Slash Commands - -The repo ships 8 slash commands under `.gemini/commands/`: 7 lifecycle commands plus the `/webperf` specialist audit. Gemini CLI auto-discovers them when you run from the project root. - -| Command | What it does | -|---------|--------------| -| `/spec` | Write a structured spec before writing code | -| `/planning` | Break work into small, verifiable tasks | -| `/build` | Implement the next task incrementally | -| `/test` | Run TDD workflow — red, green, refactor | -| `/review` | Five-axis code review | -| `/code-simplify` | Reduce complexity without changing behavior | -| `/ship` | Pre-launch checklist via parallel persona fan-out | -| `/webperf` | Audit browser-facing apps for Core Web Vitals and performance issues | - -Each command invokes the corresponding skill automatically — no manual skill loading required. - -> **Note:** Use `/planning` instead of `/plan` — `/plan` conflicts with a Gemini CLI internal command name. - -## Usage Tips - -1. **Prefer skills over GEMINI.md** — Skills activate on demand and keep your context window focused. Only put skills in GEMINI.md if you want them always loaded. -2. **Skill descriptions matter** — Each SKILL.md has a `description` field in its frontmatter that tells agents when to activate it. The descriptions in this repo are optimized for auto-discovery across all supported tools (Claude Code, Gemini CLI, etc.) by clearly stating both *what* the skill does and *when* it should be triggered. -3. **Use agents for review** — Copy `agents/code-reviewer.md` content when requesting structured code reviews. -4. **Combine with references** — Reference checklists from `references/` when working on specific quality areas like testing or performance. diff --git a/spec/agent-skills/docs/getting-started.md b/spec/agent-skills/docs/getting-started.md deleted file mode 100644 index 740f2df3..00000000 --- a/spec/agent-skills/docs/getting-started.md +++ /dev/null @@ -1,152 +0,0 @@ -# Getting Started with agent-skills - -agent-skills works with any AI coding agent that accepts Markdown instructions. This guide covers the universal approach. For tool-specific setup, see the dedicated guides. - -## How Skills Work - -Each skill is a Markdown file (`SKILL.md`) that describes a specific engineering workflow. When loaded into an agent's context, the agent follows the workflow — including verification steps, anti-patterns to avoid, and exit criteria. - -**Skills are not reference docs.** They're step-by-step processes the agent follows. - -## Quick Start (Any Agent) - -### 1. Clone the repository - -```bash -git clone https://github.com/addyosmani/agent-skills.git -``` - -### 2. Choose a skill - -Browse the `skills/` directory. Each subdirectory contains a `SKILL.md` with: -- **When to use** — triggers that indicate this skill applies -- **Process** — step-by-step workflow -- **Verification** — how to confirm the work is done -- **Common rationalizations** — excuses the agent might use to skip steps -- **Red flags** — signs the skill is being violated - -### 3. Load the skill into your agent - -Copy the relevant `SKILL.md` content into your agent's system prompt, rules file, or conversation. The most common approaches: - -**System prompt:** Paste the skill content at the start of the session. - -**Rules file:** Add skill content to your project's rules file (CLAUDE.md, .cursorrules, etc.). - -**Conversation:** Reference the skill when giving instructions: "Follow the test-driven-development process for this change." - -### 4. Use the meta-skill for discovery - -Start with the `using-agent-skills` skill loaded. It contains a flowchart that maps task types to the appropriate skill. - -## Recommended Setup - -### Minimal (Start here) - -Load three essential skills into your rules file: - -1. **spec-driven-development** — For defining what to build -2. **test-driven-development** — For proving it works -3. **code-review-and-quality** — For verifying quality before merge - -These three cover the most critical quality gaps in AI-assisted development. - -### Full Lifecycle - -For comprehensive coverage, load skills by phase: - -``` -Starting a project: spec-driven-development → planning-and-task-breakdown -During development: incremental-implementation + test-driven-development -Before merge: code-review-and-quality + security-and-hardening -Before deploy: shipping-and-launch -``` - -### Context-Aware Loading - -Don't load all skills at once — it wastes context. Load skills relevant to the current task: - -- Working on UI? Load `frontend-ui-engineering` -- Debugging? Load `debugging-and-error-recovery` -- Setting up CI? Load `ci-cd-and-automation` - -## Skill Anatomy - -Every skill follows the same structure: - -``` -YAML frontmatter (name, description) -├── Overview — What this skill does -├── When to Use — Triggers and conditions -├── Core Process — Step-by-step workflow -├── Examples — Code samples and patterns -├── Common Rationalizations — Excuses and rebuttals -├── Red Flags — Signs the skill is being violated -└── Verification — Exit criteria checklist -``` - -See [skill-anatomy.md](skill-anatomy.md) for the full specification. - -## Using Agents - -The `agents/` directory contains pre-configured agent personas: - -| Agent | Purpose | -|-------|---------| -| `code-reviewer.md` | Five-axis code review | -| `test-engineer.md` | Test strategy and writing | -| `security-auditor.md` | Vulnerability detection | -| `web-performance-auditor.md` | Core Web Vitals & performance audit (via `/webperf`) | - -Load an agent definition when you need specialized review. For example, ask your coding agent to "review this change using the code-reviewer agent persona" and provide the agent definition. - -## Using Commands - -The `.claude/commands/` directory contains slash commands for Claude Code: - -| Command | Skill Invoked | -|---------|---------------| -| `/spec` | spec-driven-development | -| `/plan` | planning-and-task-breakdown | -| `/build` | incremental-implementation + test-driven-development | -| `/build auto` | planning-and-task-breakdown → incremental-implementation + test-driven-development (whole plan, one approval) | -| `/test` | test-driven-development | -| `/review` | code-review-and-quality | -| `/code-simplify` | code-simplification | -| `/ship` | shipping-and-launch | -| `/webperf` | web-performance-auditor (specialist agent, web apps only) | - -> **Note:** When installed as a Claude Code plugin you may see a warning like -> _"Default commands/ folder is ignored because the manifest sets 'commands'"_. -> This is expected. The root `commands/` directory belongs to the Antigravity CLI -> and is intentionally separate from `.claude/commands/`. All Claude Code slash -> commands load correctly from `.claude/commands/`; the warning is cosmetic. - -## Using References - -The `references/` directory contains supplementary checklists: - -| Reference | Use With | -|-----------|----------| -| `testing-patterns.md` | test-driven-development | -| `performance-checklist.md` | performance-optimization | -| `security-checklist.md` | security-and-hardening | -| `accessibility-checklist.md` | frontend-ui-engineering | - -Load a reference when you need detailed patterns beyond what the skill covers. - -## Spec and task artifacts - -The `/spec` and `/plan` commands create working artifacts (`SPEC.md`, `tasks/plan.md`, `tasks/todo.md`). Treat them as **living documents** while the work is in progress: - -- Keep them in version control during development so the human and the agent have a shared source of truth. -- Update them when scope or decisions change. -- If your repo doesn’t want these files long‑term, delete them before merge or add the folder to `.gitignore` — the workflow doesn’t require them to be permanent. - -## Tips - -1. **Start with spec-driven-development** for any non-trivial work -2. **Always load test-driven-development** when writing code -3. **Don't skip verification steps** — they're the whole point -4. **Load skills selectively** — more context isn't always better -5. **Use the agents for review** — different perspectives catch different issues diff --git a/spec/agent-skills/docs/opencode-setup.md b/spec/agent-skills/docs/opencode-setup.md deleted file mode 100644 index 84a96d5b..00000000 --- a/spec/agent-skills/docs/opencode-setup.md +++ /dev/null @@ -1,178 +0,0 @@ -# OpenCode Setup - -This guide explains how to use Agent Skills with OpenCode in a way that closely mirrors the Claude Code experience (automatic skill selection, lifecycle-driven workflows, and strict process enforcement). - -## Overview - -OpenCode supports custom `/commands`, but does not have a native plugin system or automatic skill routing like Claude Code. - -Instead, we achieve parity through: - -- A strong system prompt (`AGENTS.md`) -- The built-in `skill` tool -- Consistent skill discovery from the `/skills` directory - -This creates an **agent-driven workflow** where skills are selected and executed automatically. - -While it is possible to recreate `/spec`, `/plan`, and other commands in OpenCode, this integration intentionally uses an agent-driven approach instead: - -- Skills are selected automatically based on intent -- Workflows are enforced via `AGENTS.md` -- No manual command invocation is required - -This more closely matches how Claude Code behaves in practice, where skills are triggered automatically rather than manually. - ---- - -## Installation - -1. Clone the repository: - -```bash -git clone https://github.com/addyosmani/agent-skills.git -``` - -2. Open the project in OpenCode. - -3. Ensure the following files are present in your workspace: - -- `AGENTS.md` (root) -- `skills/` directory - -No additional installation is required. - ---- - -## How It Works - -### 1. Skill Discovery - -All skills live in: - -``` -skills//SKILL.md -``` - -OpenCode agents are instructed (via `AGENTS.md`) to: - -- Detect when a skill applies -- Invoke the `skill` tool -- Follow the skill exactly - -### 2. Automatic Skill Invocation - -The agent evaluates every request and maps it to the appropriate skill. - -Examples: - -- "build a feature" → `incremental-implementation` + `test-driven-development` -- "design a system" → `spec-driven-development` -- "fix a bug" → `debugging-and-error-recovery` -- "review this code" → `code-review-and-quality` - -The user does **not** need to explicitly request skills. - -### 3. Lifecycle Mapping (Implicit Commands) - -The development lifecycle is encoded implicitly: - -- DEFINE → `spec-driven-development` -- PLAN → `planning-and-task-breakdown` -- BUILD → `incremental-implementation` + `test-driven-development` -- VERIFY → `debugging-and-error-recovery` -- REVIEW → `code-review-and-quality` -- SHIP → `shipping-and-launch` - -This replaces slash commands like `/spec`, `/plan`, etc. - ---- - -## Usage Examples - -### Example 1: Feature Development - -User: -``` -Add authentication to this app -``` - -Agent behavior: -- Detects feature work -- Invokes `spec-driven-development` -- Produces a spec before writing code -- Moves to planning and implementation skills - ---- - -### Example 2: Bug Fix - -User: -``` -This endpoint is returning 500 errors -``` - -Agent behavior: -- Invokes `debugging-and-error-recovery` -- Reproduces → localizes → fixes → adds guards - ---- - -### Example 3: Code Review - -User: -``` -Review this PR -``` - -Agent behavior: -- Invokes `code-review-and-quality` -- Applies structured review (correctness, design, readability, etc.) - ---- - -## Agent Expectations (Critical) - -For OpenCode to work correctly, the agent must follow these rules: - -- Always check if a skill applies before acting -- If a skill applies, it MUST be used -- Never skip required workflows (spec, plan, test, etc.) -- Do not jump directly to implementation - -These rules are enforced via `AGENTS.md`. - ---- - -## Limitations - -- No native slash commands (handled via intent mapping instead) -- No plugin system (handled via prompt + structure) -- Skill invocation depends on model compliance - -Despite these, the workflow closely matches Claude Code in practice. - ---- - -## Recommended Workflow - -Just use natural language: - -- "Design a feature" -- "Plan this change" -- "Implement this" -- "Fix this bug" -- "Review this" - -The agent will automatically select and execute the correct skills. - ---- - -## Summary - -OpenCode integration works by combining: - -- Structured skills (this repo) -- Strong agent rules (`AGENTS.md`) -- Automatic skill invocation via reasoning - -This results in a **fully agent-driven, production-grade engineering workflow** without requiring plugins or manual commands. diff --git a/spec/agent-skills/docs/skill-anatomy.md b/spec/agent-skills/docs/skill-anatomy.md deleted file mode 100644 index 5f0d336e..00000000 --- a/spec/agent-skills/docs/skill-anatomy.md +++ /dev/null @@ -1,170 +0,0 @@ -# Skill Anatomy - -This document describes the structure and format of agent-skills skill files. Use this as a guide when contributing new skills or understanding existing ones. - -## File Location - -Every skill lives in its own directory under `skills/`: - -``` -skills/ - skill-name/ - SKILL.md # Required: The skill definition - scripts/ # Optional: Runnable helpers used by the skill workflow - supporting-file.md # Optional: Reference material loaded on demand -``` - -`SKILL.md` is the only required file. Add `scripts/` only when the skill actually ships runnable helpers, and omit the directory entirely for markdown-only skills. - -## SKILL.md Format - -### Frontmatter (Required) - -```yaml ---- -name: skill-name-with-hyphens -description: Guides agents through [task/workflow]. Use when [specific trigger conditions]. ---- -``` - -**Rules:** -- `name`: Lowercase, hyphen-separated. Must match the directory name. -- `description`: Start with what the skill does in third person, then include one or more clear "Use when" trigger conditions. Include both *what* and *when*. Maximum 1024 characters. - -**Why this matters:** Agents discover skills by reading descriptions. The description is injected into the system prompt, so it must tell the agent both what the skill provides and when to activate it. Do not summarize the workflow — if the description contains process steps, the agent may follow the summary instead of reading the full skill. - -### Standard Sections (Recommended Pattern) - -The frontmatter contract above is required. The section layout below is a recommended pattern, not a rigid template: equivalent headings are acceptable when they serve the same purpose clearly. - -```markdown -# Skill Title - -## Overview -One-two sentences explaining what this skill does and why it matters. - -## When to Use -- Bullet list of triggering conditions (symptoms, task types) -- When NOT to use (exclusions) - -## [Core Process / The Workflow / Steps] -The main workflow, broken into numbered steps or phases. -Include code examples where they help. -Use flowcharts (ASCII) where decision points exist. - -## [Specific Techniques / Patterns] -Detailed guidance for specific scenarios. -Code examples, templates, configuration. - -## Common Rationalizations -| Rationalization | Reality | -|---|---| -| Excuse agents use to skip steps | Why the excuse is wrong | - -## Red Flags -- Behavioral patterns indicating the skill is being violated -- Things to watch for during review - -## Verification -After completing the skill's process, confirm: -- [ ] Checklist of exit criteria -- [ ] Evidence requirements -``` - -## Section Purposes - -### Overview -The "elevator pitch" for the skill. Should answer: What does this skill do, and why should an agent follow it? - -### When to Use -Helps agents and humans decide if this skill applies to the current task. Include both positive triggers ("Use when X") and negative exclusions ("NOT for Y"). - -### Core Process -The heart of the skill. This is the step-by-step workflow the agent follows. Must be specific and actionable — not vague advice. - -**Good:** "Run `npm test` and verify all tests pass" -**Bad:** "Make sure the tests work" - -### Common Rationalizations -The most distinctive feature of well-crafted skills. These are excuses agents use to skip important steps, paired with rebuttals. They prevent the agent from rationalizing its way out of following the process. - -Think of every time an agent has said "I'll add tests later" or "This is simple enough to skip the spec" — those go here with a factual counter-argument. - -### Red Flags -Observable signs that the skill is being violated. Useful during code review and self-monitoring. - -### Verification -The exit criteria. A checklist the agent uses to confirm the skill's process is complete. Every checkbox should be verifiable with evidence (test output, build result, screenshot, etc.). - -## Supporting Files - -Create supporting files only when: -- Reference material exceeds 100 lines (keep the main SKILL.md focused) -- Code tools or scripts are needed -- Checklists are long enough to justify separate files - -Keep patterns and principles inline when under 50 lines. - -If a skill does not need runnable helpers, do not create an empty `scripts/` directory just to mirror other skills. Empty directories add noise without changing how the skill works. - -## Context Efficiency - -Skills load on demand: only the skill name and description sit in context at startup. The full `SKILL.md` loads only when an agent decides the skill is relevant. To keep that load cheap: - -- **Keep `SKILL.md` under 500 lines.** Move detailed reference material into supporting files. -- **Write specific descriptions.** A precise description helps the agent activate the skill at the right moment and skip it otherwise. -- **Use progressive disclosure.** Reference supporting files that are read only when the workflow reaches them. -- **Prefer scripts over inline code.** Executing a script consumes no context; only its output does. Inline code blocks are paid for on every load. -- **Keep file references one level deep.** Link directly from `SKILL.md` to supporting files rather than chaining through intermediate documents. - -## Script Requirements - -When a skill ships runnable helpers under `scripts/`, each script follows these conventions: - -- Use a `#!/bin/bash` shebang. -- Use `set -e` for fail-fast behavior. -- Write status messages to stderr: `echo "Message" >&2`. -- Write machine-readable output (JSON) to stdout. -- Include a cleanup trap for temporary files. -- Reference the script path as `skills//scripts/