In the realm of AI-assisted development, two tools have significantly enhanced my workflow: Amazon Q and GitHub Spec Kit. Amazon Q has been instrumental in my development process, particularly when integrated with JetBrains IDEs. Recently, I discovered GitHub Spec Kit, a specification-driven development framework, and sought to combine these tools to create a cohesive and efficient development environment.
What is GitHub Spec Kit?
GitHub Spec Kit is an open-source toolkit designed to facilitate specification-driven development. It provides a structured process that centers around detailed specifications, which guide the implementation, planning, and task breakdowns of a project. This approach ensures that every aspect of the development process is well-documented and actionable, reducing ambiguity and enhancing collaboration.
Core Components of the Spec Kit Workflow
The Spec Kit workflow is divided into several key components:
- Specification (/spec <spec_id>): This is the foundational document that outlines the feature description, acceptance criteria, and non-functional requirements. It serves as the blueprint for the project, ensuring all stakeholders have a clear understanding of the objectives.
- Planning (/plan <spec_id>): This step involves creating a detailed plan that includes context summary, goals, scope, milestones, deliverables, dependencies, and risk mitigation strategies. It provides a roadmap for the development process.
- Task Breakdown (/tasks <spec_id>): The plan is then broken down into actionable tasks, each with assigned roles, priorities, and statuses. This decomposition facilitates manageable and trackable progress.
- Implementation (/update <file>): In this phase, the specified tasks are executed, and the corresponding files (plan.md, tasks.md, or spec.md) are updated accordingly. This ensures that the development process remains aligned with the original specifications.
Integrating Amazon Q with GitHub Spec Kit
To streamline the development process further, I created a custom rules.md file that instructs Amazon Q on how to interact with the repository using the GitHub Spec Kit workflow. This integration allows Amazon Q to generate and maintain the necessary Markdown specification files (PLAN.md, TASKS.md, SPEC.md) by invoking the provided scripts in .specify/scripts/bash/.
The rules.md file outlines specific commands and guidelines for Amazon Q to follow, ensuring consistency and adherence to the project’s principles. For instance, it specifies the use of the /plan <spec_id>, /tasks <spec_id>, and /spec <spec_id> commands to generate or update the respective files. Additionally, it emphasizes the importance of preserving the existing structure of files, using Markdown format, and respecting the project’s non-negotiable principles defined in CONSTITUTION.md.
Benefits of This Integration
By combining Amazon Q with GitHub Spec Kit, several advantages are realized:
- Enhanced Clarity: Detailed specifications and plans reduce ambiguity, leading to a more focused development process.
- Improved Collaboration: Clear task breakdowns and roles facilitate better teamwork and communication.
- Increased Efficiency: Automation of specification generation and task assignment accelerates the development cycle.
- Consistent Quality: Adherence to defined specifications ensures that the final product meets the desired standards and requirements.
Conclusion
The integration of Amazon Q with GitHub Spec Kit has transformed my development workflow, providing a structured and efficient approach to AI-assisted development. By leveraging the strengths of both tools, I have been able to enhance clarity, collaboration, and efficiency in my projects.
For a deeper understanding of Amazon Q and its capabilities, you can refer to my previous article: An Architectural Guide to LLM Assistants.
# Spec-Kit.md
## Purpose
These rules instruct Amazon Q on how to interact with this repository using the **GitHub Spec Kit** workflow.
Amazon Q must create and maintain Markdown specification files (`PLAN.md`, `TASKS.md`, `SPEC.md`) by invoking the provided scripts in `.specify/scripts/bash/`.
---
## General Rules
1. All output files must be in **Markdown (`.md`) format**.
2. The **default language** for all generated text is **English**.
3. Always preserve the existing structure of a file when updating it.
4. Never delete sections unless the user explicitly requests it.
5. Always respect the project’s non-negotiable principles defined in `CONSTITUTION.md`.
6. Scripts to run are located in `.specify/scripts/bash/` and must be used whenever possible (do not re-implement their logic).
7. If a script fails or its intent is ambiguous, Amazon Q must **ask clarifying questions** before making changes.
---
## Commands
### `/plan <spec_id>`
- Purpose: Generate or update the **plan** for a given feature/spec.
- Execution:
1. Run `.specify/scripts/bash/check-task-prerequisites.sh`.
2. Run `.specify/scripts/bash/update-agent-context.sh <spec_id>`.
3. Run `.specify/scripts/bash/setup-plan.sh <spec_id>`.
- Output: `specs/<spec_id>/plan.md` containing:
- Context summary
- Goals & scope (with MVP focus)
- Milestones & deliverables
- Dependencies
- Risks & mitigation strategies
### `/tasks <spec_id>`
- Purpose: Generate or update the **tasks** for a given feature/spec.
- Execution:
1. Ensure prerequisites are valid.
2. Use `.specify/scripts/bash/get-feature-paths.sh <spec_id>` to locate the spec files.
3. Create or update `specs/<spec_id>/tasks.md` from `tasks-template.md`.
- Output: `tasks.md` with:
- Task breakdown
- Assigned roles
- Priority & status (Todo/In Progress/Done)
- Dependencies between tasks
### `/spec <spec_id>`
- Purpose: Generate or update the **feature specification**.
- Execution:
1. Ensure prerequisites are valid.
2. Use `.specify/scripts/bash/create-new-feature.sh <feature_name>` if the feature doesn’t exist.
3. Otherwise, update `specs/<spec_id>/spec.md` using `spec-template.md`.
- Output: `spec.md` with:
- Feature description
- Acceptance criteria
- Non-functional requirements (performance, security, accessibility, etc.)
### `/update <file>`
- Purpose: Update the specified file (`plan.md`, `tasks.md`, or `spec.md`).
- Rules:
- Preserve structure and headings.
- Only insert or update requested content.
- Ask for clarification if the update is ambiguous.
---
## Integration Rules
### If Amazon Q has shell access
- Commands are executed directly using bash:
```bash
chmod +x .specify/scripts/bash/*.sh
.specify/scripts/bash/<script>.sh <args>
Leave a Reply