Repository Layout

Repository Layout

AGENTS.md                          constitution — Copilot native, Claude via CLAUDE.md
CLAUDE.md                          one line: @AGENTS.md

.claude/
  rules/*.md                       SHARED path-scoped rules (paths:)
  commands/sdd-*.md                SHARED workflow bodies — Claude runs them as /sdd-*
  settings.json                    SHARED, version-controlled Claude settings
                                   (settings.local.json is local and git-ignored)

.github/
  prompts/sdd-*.prompt.md          Copilot loaders — one line each, point at the body
  agents/SpecDrivenAgent.agent.md  Copilot-only persona

.vscode/settings.json              makes the interop explicit

.specs/                            shared data: backlog/ active/ done/  (+ README)
                                   ships EMPTY — your first spec is 0001
                                   NNNN-slug.md + NNNN-slug.plan.md per feature
.memory-bank/                      shared data: projectbrief, systemPatterns,
                                                activeContext, techContext
docs/history/                      how FeatherSpec itself was built — delete it in your project
README.md, LICENSE, .gitignore

.specs/ ships empty on purpose. FeatherSpec's own build briefs used to sit in .specs/done/, which meant a cloned template arrived with somebody else's history in the folder meant for yours — your first spec would have been numbered 0003, and the two files you would read to learn the format predated the plan mandate and taught a shape the commands no longer produce. They now live in docs/history/, clearly labelled as ours, and that folder is safe to delete.

AGENTS.md — the constitution

The single, tool-neutral source of truth. Copilot reads it natively; Claude Code gets it through the @AGENTS.md import in CLAUDE.md. It holds:

• DocLanguage — the language of your project documentation
• the architecture: snapshot — style, entrypoints, modules, shared components, boundaries
• Style & Output Preferences — a living record of your stated coding preferences
• the non-negotiables, the spec and plan lifecycle policy, and the Memory Bank file set

Everything mutable lives here and only here. Commands that change those values write to this file. No loader may hold a copy — that duplication is exactly the drift this design exists to prevent. Target length: under 200 lines.

CLAUDE.md — one line

@AGENTS.md

That is the whole file. It exists so Claude Code loads the constitution at session start. It holds no rules of its own, and it never will.

.claude/rules/ — path-scoped craft rules

Each rule file declares a paths: list in its frontmatter and loads when a matching file is read. Both tools understand them (VS Code reads paths: where its own instruction files use applyTo:).

File	Applies to	Covers
constitution.md	AGENTS.md	how to edit the constitution itself
specs.md	.specs/**/*.md	how to write a spec file
plans.md	.specs/**/*.plan.md	how to work inside a plan file
memory-bank.md	.memory-bank/**/*.md	how to write Memory Bank files, incl. the activeContext.md structure
repo-docs.md	README and docs/	documentation language

AGENTS.md states policy; rule files state craft. The constitution defines the spec and plan lifecycle and the Memory Bank file set. The rule files cover only how to write those files, and link back to AGENTS.md for the policy.

.claude/commands/ — the workflow bodies

Nine files, one per command. Claude Code exposes each as /<filename-without-extension>. Each body carries frontmatter:

---
description: One-line summary shown in the / menu.
argument-hint: "[thing]"
disable-model-invocation: true
---

and an HTML comment at the top restating the shared-body constraints so nobody reintroduces Claude-only syntax later. See Extending FeatherSpec.

.github/prompts/ — the Copilot loaders

One file per command, and each is a pointer, not a rule:

---
name: sdd-plan
description: Turn a spec into a persisted baby-step plan file with research and traceability.
argument-hint: "[path to spec or plan]"
---

# /sdd-plan

Follow [`.claude/commands/sdd-plan.md`](../../.claude/commands/sdd-plan.md) exactly — read that
file first and treat it as your instructions for this turn. It is the single source for this
workflow; this file only points at it and holds no rules of its own.

Anything the user typed after the command is the argument the workflow refers to.

They exist because Copilot has no other way to expose a slash command: the folder and the .prompt.md extension are both required, so one file cannot serve both tools.

There is deliberately no .github/instructions/ and no .github/copilot-instructions.md — they would only duplicate what .claude/rules/ and AGENTS.md already provide.

.specs/ and .memory-bank/ — your data

These two folders are the project's actual content, and they are tool-neutral: plain Markdown that both assistants read and write. In the predecessor template they lived under .github/; moving them to the top level made them visible as data rather than tool configuration.

See Specs and Plans and Memory Bank.

What is not here

• No skills. Deliberate — see Design Decisions.
• No MCP servers. .mcp.json / .vscode/mcp.json are documented in Configuration for when you add your own.
• No hooks. Documented in Configuration, including the VS Code matcher caveat.
• No build step, no dependencies, no lock file. If a feature cannot be expressed in Markdown plus native tool configuration, it does not belong here.