Architectural review: improvements and refactors

[Ilyes512]

Context

This is a tracker for follow-ups from the architectural review of specs-cli performed on 2026-05-07. The full review is at #42 (comment). Each sub-issue below corresponds to one numbered item in that review and is self-contained: it states the concern, points to the file/line locations, and proposes a direction. Future contributors (humans or LLMs) should be able to pick up any sub-issue without reading the others.

Scope

The review covered: pkg/cmd, pkg/template, pkg/hooks, pkg/host, pkg/specs, pkg/util, the CI/release setup, and the architecture docs under docs/content/docs/architecture/.

Strengths (no action needed, captured for context)

• Clean package layering: pkg/cmd (orchestration) → pkg/template (engine) → pkg/util/* (primitives). The rule "pkg/template must not import pkg/cmd" is honored.
• AST-driven analysis in pkg/template/analysis.go walks the text/template parse tree to discover both referenced and conditional variables, enabling the iterative dependency-aware prompting in pkg/cmd/template_use.go.
• output.Writer abstraction with Human and JSON implementations is well-designed; NDJSON for streaming is a good choice.
• Architecture docs document why, not just what.
• GoReleaser + Homebrew + Docker-based dev workflow is mature.

Sub-issues

High-impact

• Extract pkg/registry; consolidate project-file readers #43 — Extract pkg/registry; consolidate project-file readers
• --safe-mode should imply --no-hooks; harden hook execution #44 — --safe-mode should imply --no-hooks; harden hook execution
• Make computed-defaults code path consistent (copy-on-write) #45 — Make computed-defaults code path consistent (copy-on-write)
• Default to fail-fast on template render errors #46 — Default to fail-fast on template render errors
• Improve binary-file detection in template engine #47 — Improve binary-file detection in template engine

Medium-impact

• Stricter validation of GitHub source format #48 — Stricter validation of GitHub source format
• Bound concurrency and add timeouts in template list status refresh #49 — Bound concurrency and add timeouts in template list status refresh
• Consistent error wrapping with sentinel errors #50 — Consistent error wrapping with sentinel errors
• Improve observability via structured logging #51 — Improve observability via structured logging
• Add E2E integration tests with testdata fixtures #52 — Add E2E integration tests with testdata fixtures
• Document Dockerfile and compose.yml purpose in README #53 — Document Dockerfile and compose.yml purpose in README

Lower-impact polish (bundled checklist)

• Lower-impact polish (bundled checklist) #54 — Lower-impact polish (bundled)

Suggested ordering

If prioritizing a sprint:

1. Safety: imply --no-hooks from --safe-mode; fail-fast on render errors with opt-in continue (--safe-mode should imply --no-hooks; harden hook execution #44, Default to fail-fast on template render errors #46).
2. Refactor: extract pkg/registry and consolidate the project-file readers (Extract pkg/registry; consolidate project-file readers #43).
3. Robustness: bound goroutines + add timeouts in list (Bound concurrency and add timeouts in template list status refresh #49); tighter source parsing (Stricter validation of GitHub source format #48).
4. Polish: error wrapping pass (Consistent error wrapping with sentinel errors #50); structured logging on hot paths (Improve observability via structured logging #51); E2E integration tests (Add E2E integration tests with testdata fixtures #52).