Skip to main content
Suspec
manual page/ ADRs

ADR-0062 — Code-repo adapter: pristine today, gitignored CLI state when a CLI exists

sourceSource: suspec/docs/adrs/0062-code-repo-adapter.mdModified: 2026-06-30
Sections
6
Format
Markdown
Order
98 / 156

Context

Suspec's workspace holds intent and evidence; code repos hold code. The committed-dotdir norm (.github/, .vscode/) shows teams tolerate committed tool directories, but a spec workflow that litters every implementing repo multiplies its footprint by the number of repos and couples them to the workspace's conventions. ADR-0050 already allows gitignored scratch in code repos.

Decision

  1. Today (no Suspec tooling ships): a code repo needs nothing. At most: a one-line pointer in its AGENTS.md ("Suspec workspace: <path/url>; read the task packet you are given"), the kit's .gitignore.additions, and optionally the implement-task agent guide copied into the repo's skills directory. Task packets are handed to the agent by paste or path; transient files stay gitignored. The PR links the workspace review packet — the PR is the merge mechanism, the packet is the record.
  2. When a CLI exists, it may own a fully gitignored .suspec/ local-state directory in code repos (config.yaml, work/, cache/, tmp/) — machine state in the .git//node_modules/ sense, never committed, never required by the markdown workflow, specified only on the future-CLI page.
  3. Committed Suspec content in code repos remains out of bounds (convention level): specs, reviews, and findings belong to the workspace.

Alternatives considered

AlternativeWhy weaker
Committed .suspec/ in code repos (the dotdir norm)Multiplies footprint across repos; couples every repo to workspace conventions; the workspace already is the committed home
Forbid .suspec/ even for the future CLIA CLI needs local state; pretending otherwise re-creates dishonest docs

Consequences

Positive: adopting Suspec never dirties a product repo. Negative: agents must be pointed at the workspace explicitly. Neutral: deviates deliberately from the committed-dotdir norm (recorded counter-evidence).

Status

Accepted. Reaffirms ADR-0049 and ADR-0050 (clarification; the gitignored-scratch clause of 0050 is the ground for §2).

Propagation

docs/03/07/10, ADOPTING, kit .gitignore.additions + implement-task guide, future-cli page.

Starter kit: Set up a workspace