Configuration

Configuration

FeatherSpec ships with almost no configuration on purpose. This page covers the few knobs that exist, and the two integrations (MCP, hooks) that ship as documentation so you can add them yourself.

DocLanguage

Lives in AGENTS.md, and only there:

DocLanguage: English # default; /sdd-setup may change this. Governs the user's project docs
                     # (Memory Bank, specs, README) and all workflow dialogue; wiring stays English.

It governs the language of your project documentation — the Memory Bank, your specs and plans, your README — not FeatherSpec's own wiring, which stays English. /sdd-setup sets it as its very first question; you can also edit the line directly.

Every command writes its output in DocLanguage, including the interviews and reports.

FeatherSpecVersion

Also in AGENTS.md's managed settings block:

FeatherSpecVersion: 1.2.0 # managed by /sdd-featherspec-update; do not edit by hand

/sdd-featherspec-update manages it and is the only thing that writes it. Projects adopted before 1.2.0 carry no stamp — the version is then estimated from feature probes. See Updating & Versioning.

The architecture: snapshot

Also in AGENTS.md, also only there:

# last reconciled: never · last deep scan: never
architecture:
  style: 'TBD'
  entrypoints:
    - 'TBD'
  modules: []
  shared: []
  boundaries:
    - 'TBD'

/sdd-setup fills it in for the first time — on existing software it offers /sdd-architecture-scan, which builds it from the code — and /sdd-architecture-update reconciles it with the real tree later. The assistant spots drift during normal work and proposes the update; the write itself happens only behind /sdd-architecture-update's confirmation gate, and when drift is too large to reconcile confidently, the delta report recommends /sdd-architecture-scan instead. The comment line records when each last happened.

.sdd-scan/

/sdd-architecture-scan keeps its working state — inventory, worklist, scout reports — under .sdd-scan/. It is the template's only volatile folder: gitignored, safe to delete at any time (everything curated moves on to the snapshot, the .architecture/ maps and the Memory Bank), and the reason a scan survives any interruption — the worklist is the resume point, and the scan offers the cleanup itself after a confirmed merge.

Team resume: scan state is machine-local by default. To let a colleague continue a half-finished scan, remove the .sdd-scan/ lines from .gitignore and commit the folder; the next /sdd-architecture-scan on any machine resumes from the committed worklist.

Scout model

The sdd-scout agent files ship without a model: field — scouts inherit your session model. That is deliberate: the template prescribes no model in either tool; which model does the reading is your call, per session or per repository.

The cost mechanics, so the call is informed: the scan's biggest price lever is the model the scouts run on. The simplest control is picking a cheaper model for the whole scan session. Both dialects also support pinning locally — model: haiku in the Claude dialect (a generation-stable alias) or e.g. model: ['Claude Haiku 4.5', 'GPT-5 mini'] in the VS Code dialect (a prioritized list; VS Code resolves invocation parameter → frontmatter → main model, and a subagent can never exceed the main model's cost tier). Cheap models are a reasonable fit for scouts: since the read ladder their job is a tight corset (schema, budgets, split rule, name-trap rule), and Claude Code's own built-in Explore agent runs on haiku for the same reason — while the synthesis (Phase C) benefits from a capable model.

Whatever you choose, quality is gated, not assumed: the navigation self-test (≥ 8/10) plus the surface-cue probe decide. A cheap model that passes has earned its place; one that fails has refuted the saving itself. If you do pin locally: model display names age — re-check them when updating the template (/sdd-featherspec-update's final report reminds you about pinned models); the Copilot cloud agent ignores VS-Code-specific frontmatter properties, so extra fields break nothing there.

Model choice per workflow

A rule of thumb our validation runs kept confirming: reading scales down, judgment does not. Workflows whose value is judgment — the /sdd-setup wizard, /sdd-specify interviews, /sdd-plan design work, and the scan's synthesis plus the /sdd-architecture-update gate — reward a strong reasoning model. Reading-heavy work — the scan's scouts — runs fine on cheap models. The model picker is the lever, per session; no configuration needed. Scan-specific pattern: run the scan on a cheap session model, and if the navigation self-test or your own spot checks complain about the distilled result, switch the picker to a stronger model and say "distill what we have" — Phase C re-runs from the kept reports at a fraction of the scan's cost.

Shared vs. local Claude settings

File	Scope	Committed
.claude/settings.json	everyone who clones the repository	yes
.claude/settings.local.json	your machine, your user	no — git-ignored
CLAUDE.local.md	your machine, your user	no — git-ignored

Claude Code writes settings.local.json when you grant a permission with "don't ask again", so it holds machine- and user-specific rules. Committing it would push your personal permission set onto the whole team. The shipped .gitignore excludes it, along with CLAUDE.local.md, the documented local-only memory variant (which VS Code also detects).

Put anything the team should share in .claude/settings.json and AGENTS.md.

Note that VS Code reads hooks from .claude/settings.local.json too — so a local hook affects both tools on your machine.

Auto memory is off on purpose

{
  "autoMemoryEnabled": false
}

Claude Code's auto memory is a machine-local, per-repository note store at ~/.claude/projects/<project>/memory/ — effectively a second, invisible Memory Bank. It is not in your repository, your teammates never see it, and it is not reviewable in a pull request. This template keeps exactly one visible source of truth.

To re-enable it, set the key to true or remove it. Copilot ignores this key entirely — its memory is a separate system with a separate switch, covered next.

Copilot memory

"Copilot memory" is two separate systems, and only one of them lives on your machine:

1. GitHub Copilot Memory (Preview) — server-side and repo-scoped, toggled per account at github.com/settings/copilot/features. Turning it off there does not govern the local tool below.

2. The local memory tool of VS Code's copilot-chat extension — plain files on your disk:

   OS	User-scope location
   Windows	%APPDATA%/Code/User/globalStorage/github.copilot-chat/memory-tool/memories/
   macOS	~/Library/Application Support/Code/User/globalStorage/github.copilot-chat/memory-tool/memories/
   Linux	~/.config/Code/User/globalStorage/github.copilot-chat/memory-tool/memories/

   The user scope auto-injects the first 200 lines of its files into every session on the machine, in every project; repo- and session-scoped files live under workspace storage. Inspect it with Chat: Show Memory Files, wipe it with Chat: Clear All Memory Files.

The shipped github.copilot.chat.tools.memory.enabled: false disables both writing and injection — with honest limits: some bundled builds ship without the key at all, and vscode issue #318131 (still open) reports memory writes despite the setting (injection-despite-disabled was fixed in June 2026). So the setting is the first line of defense, not the last. The last is FeatherSpec's own guard, the AGENTS.md preference-capture rule: a preference exists only as a bullet there. Anything the assistant claims to know from tool memory is proposed and asked about, never silently followed — and the proposal must name its source ("from my saved user memory"), never a vague "your notes".

MCP

FeatherSpec ships no MCP servers. If you add some, each tool reads its own file — neither reads the other, and no setting relocates them:

Tool	File	Root key
Claude Code	.mcp.json	mcpServers
VS Code Copilot	.vscode/mcp.json	servers

The server definitions inside are otherwise identical, so maintaining both is a copy of the same object under a different key.

Hooks

FeatherSpec ships none, but a hooks block in .claude/settings.json is read by both tools. Three caveats if you add one:

1. VS Code ignores matcher values. Hooks fire on every tool invocation, so any shared hook must filter on tool_name inside the script itself.
2. The input shape differs. VS Code uses camelCase (tool_input.filePath) and its own tool names; Claude Code uses snake_case (tool_input.file_path). A shared hook has to handle both.
3. Hooks are a Preview feature in VS Code. If yours do not fire, check the chat.useClaudeHooks setting.

Copilot also has its own hooks file at .github/hooks/hooks.json if you decide to go Copilot-only later — see Committing to One Tool.

.vscode/settings.json

Every path FeatherSpec relies on is already a VS Code default. The shipped file restates them — and deliberately flips two locations off — so the setup survives a changed default or an overriding workspace:

{
  "chat.useAgentsMdFile": true,
  "chat.useClaudeMdFile": false,
  "chat.instructionsFilesLocations": { ".github/instructions": true, ".claude/rules": false },
  "chat.promptFilesLocations": { ".github/prompts": true },
  "chat.agentFilesLocations": { ".github/agents": true, ".claude/agents": false },
  "github.copilot.chat.tools.memory.enabled": false
}

chat.useClaudeMdFile is off because Copilot reads AGENTS.md natively — the one-line CLAUDE.md import file would be redundant for it. chat.instructionsFilesLocations points at .github/instructions and flips .claude/rules off because VS Code cannot read instruction files from .claude/rules — Copilot reaches the rules instead through six thin loaders under .github/instructions/ (one <name>.instructions.md per rule, its applyTo mirroring the rule's paths: globs, its body pointing at the .claude/rules single source; the loaders hold no rules themselves). .claude/agents is off because that folder holds the deep scan's scout in Claude dialect, and VS Code reading it would surface a duplicate scout with an unrestricted tool set — the VS Code dialect lives in .github/agents/. github.copilot.chat.tools.memory.enabled is the Copilot counterpart to autoMemoryEnabled: false — see Copilot memory above for what it does and does not switch off. See Interop Matrix.