Recommended approach for brownfield development

[linusnikander]

I have an existing application (microservice architecture with many APIs) that wasn’t originally defined in spec-kit.

What is the recommended approach to importing/syncing those existing API definitions (and other relevant information/decisions that would be captured in the spec-kit format had i started using it from the start) so spec-kit is aware of them through it's structured format so that future development can build on top of what’s already there?

[jflam]

A really powerful approach is to have the agent go and research your existing codebase and write it down in a research doc. Then you refer to that research doc from the specs that you are writing. Think about the doc as being a "compressed view" of your codebase.

[czei]

I have the same question: how to install this into existing projects. I assume its an MCP server, but the installation process is very odd, assumming there's no existing code:

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

Where are the instructions to just install the MCP server into a commandline AI platform?

[adam-paterson]

This isn't an MCP server implementation (yet). It's an agent orchestration framework.

The installer will create some commands/prompt in your agent tool of choice.

Then when you using the "custom command/prompts" the LLM follows the workflow defined to create a spec.

[czei]

Hey, thanks for the clarification. I eventually figured that out from looking at a release. :-).

Trying the uvx installation method out on a sample directory, it appears to create a custom shell with commands already installed, which, as a long-time commandline user, I'm uncomfortable with. I want to know what commands are installed in my shell, but that's just me.

Trying to install with uvx for an existing project fails with an error, so I guess that's not a recommended installation method.

I also tried downloading the release for Claude Code in a zip and copying those files into my existing project, but running /specify inside claude code doesn't seem to create the files shown in the greenfield demos. I assume there's some difference between the commandline command "specify" and "/specify" inside of CC. For example, the detailed scription of how a project is supposed to be setup lists many files, none of which are created by "/specify".

├── memory
│ ├── constitution.md
│ └── constitution_update_checklist.md
├── scripts
│ ├── check-task-prerequisites.sh
│ ├── common.sh
│ ├── create-new-feature.sh
│ ├── get-feature-paths.sh
│ ├── setup-plan.sh
│ └── update-claude-md.sh
├── specs
│ └── 001-create-taskify
│ ├── contracts
│ │ ├── api-spec.json
│ │ └── signalr-spec.md
│ ├── data-model.md
│ ├── plan.md
│ ├── quickstart.md
│ ├── research.md
│ └── spec.md
└── templates
├── CLAUDE-template.md
├── plan-template.md
├── spec-template.md
└── tasks-template.md

That begs the question, where is the "specify" command shown in the greenfield demo, which presumably creates the above file structure. It doesn't appear to be in the release:

czei@Czei Downloads % unzip spec-kit-template-claude-sh-v0.0.39.zip
Archive: spec-kit-template-claude-sh-v0.0.39.zip
creating: .specify
creating: .specify/scripts
creating: .specify/scripts/bash
inflating: .specify/scripts/bash/setup-plan.sh
inflating: .specify/scripts/bash/common.sh
inflating: .specify/scripts/bash/check-task-prerequisites.sh
inflating: .specify/scripts/bash/update-agent-context.sh
inflating: .specify/scripts/bash/create-new-feature.sh
inflating: .specify/scripts/bash/get-feature-paths.sh
creating: .specify/memory
inflating: .specify/memory/constitution_update_checklist.md
inflating: .specify/memory/constitution.md
creating: .specify/templates
inflating: .specify/templates/tasks-template.md
inflating: .specify/templates/agent-file-template.md
inflating: .specify/templates/plan-template.md
inflating: .specify/templates/spec-template.md
creating: .claude
creating: .claude/commands
inflating: .claude/commands/plan.md
inflating: .claude/commands/tasks.md
inflating: .claude/commands/specify.md

[r3core]

@czei Did you try uvx --from git+https://github.com/github/spec-kit.git specify init --here?

[czei]

@czei Did you try uvx --from git+https://github.com/github/spec-kit.git specify init --here?

The documentation doesn't actually say that-- instead it says "specify init --here", which is not a command included in the zip file.

Never-the-less, I did try the full uvx command and it does not create any folders outside of the .specify folder, which I assume holds the original templates. There's no README, so its impossible to say, but the only possible reason to hide things in a .specify directory would be that they are not to be edited as part of the project.

mkdir dogpoo
cd dogpoo
uvx --from git+https://github.com/github/spec-kit.git specify init --here
czei@Czei dogpoo % ls -la
total 0
drwxr-xr-x 5 czei staff 160 Sep 18 20:43 ./
drwxr-xr-x 3 czei staff 96 Sep 18 20:43 ../
drwxr-xr-x@ 3 czei staff 96 Sep 18 20:43 .claude/
drwxr-xr-x@ 12 czei staff 384 Sep 18 20:43 .git/
drwxr-xr-x@ 5 czei staff 160 Sep 18 20:43 .specify/

[jeremyeder]

At the very least, do something like /init with Claude and then review it...

[tonykay]

I'd love to see an "ingester" agent/capability or, as @jeremyeder mentions, /init, perhaps /init ingest that can traverse an existing code base, consuming:

• readmes
• docs
• code (and code > docs as docs traditionally drift or represent wishes v reality)

What is not clear to me is the outputs, which may well include recognizing security, technical concerns, poor practices, TODOs, etc

[nishantc7]

As mentioned here, maybe we can check how well repomix does?
#155 (comment)