feat(cli): add agk run command to close the run→observe loop

[kunalkushwaha]

What

Adds a first-class agk run [path] command — the missing center of the developer loop. Today AGK scaffolds and observes but never runs; agk init just tells you to go run main.go. This welds scaffold → run → observe into a single tool.

This is feature B1 from the new FEATURES.md roadmap (the #1 priority).

Behavior

• Wraps go run . in the target directory, inheriting stdio.
• Tracing on by default: sets AGK_TRACE=true + AGK_TRACE_EXPORTER=file so the run is captured to .agk/runs/<run-id>/.
• On exit, locates the run produced by this invocation and prints a compact trace summary (duration / spans / LLM calls / tokens / est. cost) plus a → agk trace view <run-id> hint. Reuses the existing trace helpers in cmd/trace.go.

Flags

Flag	Description
--watch / -w	Re-run on .go changes (debounced)
--no-trace	Run without tracing (skips the summary)
--trace-level	minimal | standard (default) | detailed → sets AGK_TRACE_LEVEL

Testing

• go build, go vet, go test ./... all green.
• Verified end-to-end against a self-contained project (no framework/LLM needed):
  • happy path: run → trace captured → summary printed;
  • --no-trace: tracing disabled, no summary;
  • --watch: initial run → file change detected → clean re-run with a fresh trace.
• Error paths: missing go.mod, invalid --trace-level.

Also included

• FEATURES.md — prioritized DX/agent-building roadmap (grounded in code references).
• CLAUDE.md — repository guide for future contributors/agents.
• .gitignore — excludes build artifacts and .agk/ runtime output.
• Promotes fsnotify to a direct dependency (used by --watch).

Follow-ups (noted in FEATURES.md)

• A dedicated agk dev alias.
• Make agk trace path-aware so summaries for agk run <subdir> link correctly from any CWD.

🤖 Generated with Claude Code