Skip to main content

Spec Kit with Amazon Q Developer: Findings and Quirks

· 4 min read
Akhan Zhakiyanov
Akhan Zhakiyanov
Lead engineer

I recently explored further spec-driven development using GitHub's Spec Kit with Amazon Q Developer. This became possible after the Amazon Q Developer team merged PR #2799 (custom prompt support) and the Spec Kit team merged PR #600 (Q Developer integration).

Here's what I discovered along the way - the good, the quirks, and the gotchas.

Versions Used
  • Spec Kit: 0.0.64
  • Amazon Q CLI: 1.17.0
Amazon Q Developer CLI warning banner

Installation: Same as Before (Except One Thing)​

The installation process hasn't changed from when I set it up previously, except now the --ai parameter accepts q:

# Install Spec Kit
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# Verify it works
specify --help

# Initialize in your project
cd /path/to/your/project
# NEW: --ai parameter now accepts 'q' for Q Developer
specify init --here --ai q

That's it. No complex configuration, just install and initialize with Q Developer as your AI assistant.

Finding #1: It's CLI Only (Not in VS Code)​

Important to know: Spec Kit with Q Developer only works in the Q CLI, not in the VS Code Q chat extension.

You need to use the terminal to access Spec Kit functionality:

# Start Q CLI
q

# Check what's available
/prompts

Once in Q CLI, you'll see all the Spec Kit prompts listed. It's a terminal-first workflow, which actually makes sense for spec-driven development.

Finding #2: Spec Kit Now Uses the speckit. Prefix​

Second discovery: Spec Kit has changed since my last blog post - all commands are now namespaced with speckit.

When you run /prompts, you'll see:

  • speckit.specify - Create specifications
  • speckit.plan - Generate implementation plans
  • speckit.implement - Generate code
  • speckit.tasks - Break down work into tasks
  • speckit.analyze - Analyze project structure

This is different from my previous experience. Back then, Spec Kit used simple commands like specify, plan, implement. Now everything is prefixed with speckit. across all AI assistants.

The prefix makes sense - it provides clear namespace separation when working with multiple prompt systems. It's more explicit and avoids potential naming conflicts.

Finding #3: Two Working Syntaxes​

Third discovery: There are two ways to invoke Spec Kit commands that actually work.

Option 1: Command in quotes, text after

'@speckit.specify text to pass'

Example:

'@speckit.specify REST API with TypeScript, PostgreSQL, and JWT authentication'

Option 2: Using $ARGUMENTS with the @ symbol

$ARGUMENTS='text in quotes' @speckit.command

Example:

$ARGUMENTS='REST API with TypeScript, PostgreSQL, and JWT authentication' @speckit.specify

Both syntaxes use the @ symbol - the difference is whether you put the command in quotes or use $ARGUMENTS to pass the text.

Finding #4: The Quirky Workaround​

Fourth discovery: Occasionally, even with proper syntax, commands don't work on the first attempt:

# First attempt - sometimes doesn't work
'@speckit.specify REST API with authentication'
# or
$ARGUMENTS='REST API with authentication' @speckit.specify

When this happens, the workaround is to run the command again without arguments:

# Second attempt - Q Developer picks it up from history
'@speckit.specify'

On the second run, Q Developer retrieves the arguments from the command history and processes them correctly. It's a bit odd, but once you know this pattern, it becomes part of the workflow.

The pattern: If your first attempt doesn't work, immediately run just @speckit.command without arguments. Q will pick up the description from history.

Quick Reference​

For future me (and you):

# Installation
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify init --here --ai q

# Commands in Q CLI - Two syntaxes:
# Option 1: Command in quotes with text
'@speckit.specify your description'
'@speckit.plan your-spec.md'
'@speckit.implement module name'

# Option 2: $ARGUMENTS syntax
$ARGUMENTS='your description' @speckit.specify
$ARGUMENTS='your-spec.md' @speckit.plan

# If doesn't work, run the command again without args
'@speckit.specify'

I'm keeping an eye on the progress of both Spec Kit and Q Developer integration. As things evolve, I'll keep you updated with new findings and improvements.

Happy spec-driven development! 🚀