Getting Started

Getting Started

FeatherSpec is not a program. There is nothing to install, nothing to build, and no dependencies. Getting started means getting the files into a folder and opening that folder in your assistant.

1 · Get the template

Three ways, pick one:

Use this template (recommended for a new project)

Click Use this template on GitHub. You get a fresh repository with no shared history.

Clone — works everywhere, no extra tooling

git clone https://github.com/GregorBiswanger/featherspec.git my-project
cd my-project

You now have this repository's full commit history and a remote pointing back here. Keep both if you want to pull template updates later. For a project of your own, drop them and start clean:

rm -rf .git
git init

On Windows PowerShell that first line is Remove-Item -Recurse -Force .git.

degit — files only, needs Node.js

degit downloads the current file state and nothing else: no commit history, no .git folder, no remote to detach. It does the same job as clone-then-reset in one line — but it needs Node.js on your machine, so it is a convenience, not the baseline.

npx degit GregorBiswanger/featherspec my-project
cd my-project
git init

Adding it to an existing project? Copy AGENTS.md, CLAUDE.md, .claude/, .github/prompts/, .github/agents/, .vscode/settings.json, .specs/ and .memory-bank/ into your repository. If you already have an AGENTS.md, merge FeatherSpec's sections into yours rather than replacing it — it is the single source of truth for both tools.

2 · Open it in Claude Code

cd my-project
claude

• CLAUDE.md is one line — @AGENTS.md — so the constitution loads at session start, every session.
• Type / and the nine sdd- commands appear. Claude Code discovers new files in .claude/commands/ without a restart.
• Nothing else is needed. .claude/settings.json ships with the template and is version-controlled.

3 · Open it in GitHub Copilot (VS Code)

1. Open the project folder itself in VS Code — not a parent folder. Slash commands are discovered from the workspace root, so opening one level too high makes them disappear. This is the single most common setup mistake.
2. Open Copilot Chat: Ctrl/Cmd + Alt + I.
3. Switch the chat to Agent mode. The workflows read and write files, which only agent mode can do.
4. Optionally pick the SpecDrivenAgent persona from the agent dropdown (.github/agents/SpecDrivenAgent.agent.md).
5. Type / and confirm you see sdd-setup, sdd-specify, sdd-clarify, sdd-plan, sdd-compile, sdd-lifecycle, and the rest.

Missing? Restart VS Code completely — not just a window reload. If they are still missing, see Troubleshooting.

AGENTS.md, .claude/rules, .github/prompts and .github/agents are all default locations in VS Code, so a fresh clone works as-is. The shipped .vscode/settings.json restates them explicitly so the setup survives a changed default:

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

chat.useClaudeMdFile is deliberately off: Copilot reads AGENTS.md natively, so the one-line import file would be redundant for it. See Interop Matrix.

4 · Run /sdd-setup once

/sdd-setup

The wizard:

1. Asks for your documentation language first. Answer English, Deutsch, Français, or anything else. It is stored as DocLanguage in AGENTS.md and governs the language of your Memory Bank, your specs and your project README from that point on. FeatherSpec's own wiring stays English.
2. Asks about project name, primary users, tech stack, architecture style, entrypoints, quality gates and coding preferences.
3. Seeds .memory-bank/projectbrief.md, techContext.md, systemPatterns.md and activeContext.md in that language.
4. Captures a first architecture: snapshot in AGENTS.md from the actual folder layout, and asks you to confirm anything it had to assume.
5. Records your stated style preferences under Style & Output Preferences in AGENTS.md.

You only run this once per repository.

5 · Verify what actually loaded

Worth doing once, so you trust the setup later.

Tool	How
Claude Code	/context — shows the loaded memory files and their sizes
Claude Code	/memory — inspect and edit what is in memory
VS Code Copilot	Right-click in the Chat view → Diagnostics — lists every loaded agent, skill and instruction file with its load status

You should see AGENTS.md loaded in both.

The loop, in one line

/sdd-specify → /sdd-clarify → /sdd-plan → read the plan → implement → /sdd-compile → /sdd-lifecycle.

Two of those steps are a human reading something rather than a tool producing something, and they are the two with the highest leverage. /sdd-clarify is a command, but its job is to make you decide about the gaps it found; the plan review has no command at all, because nobody can outsource agreeing with a plan.

And not every change deserves the loop. A typo, a config value, a one-line fix with an obvious test: say you are taking the fast path and take it. AGENTS.md says work spec-first for anything that changes behaviour — deliberately not always.

Next

• Hands-On Walkthrough — run one complete cycle on a toy project
• Commands — what each command actually does
• Or just run /sdd-overview and let the assistant orient you