Skip to content

Conversation

Copy link
Contributor

Copilot AI commented Dec 16, 2025

Users need comprehensive documentation on using spec-kit with gh-aw for spec-driven development, including directory structure, workflow commands, and practical examples.

Documentation Added

  • Main guide (docs/src/content/docs/guides/spec-kit-integration.md, 556 lines)

    • Spec-driven development workflow: constitution → specification → plan → tasks → implementation
    • Directory structure (.specify/) and file organization
    • Creating specifications, plans, and task breakdowns
    • Automated executor workflow operation (runs daily at 8am UTC)
    • Spec-kit commands reference: /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement
    • Best practices and troubleshooting
    • Follows Diátaxis framework (how-to guide structure)
  • Complete example (.specify/specs/example-feature/, 1,109 lines)

    • Workflow validation report feature demonstrating realistic complexity
    • spec.md: User stories, functional/non-functional requirements, success metrics
    • plan.md: Go-based architecture, TDD strategy, component design
    • tasks.md: Phase-based task breakdown (Setup → Tests → Core → Integration → Polish)
    • README.md: Usage guide and learning points

Repository Updates

  • README.md: Added "Spec-Driven Development" section linking to quick start, guide, and example
  • AGENTS.md: Added "Spec-Kit Integration" section with directory structure, constitution reference, commands, and guidelines for AI agents working with specifications

Example Usage

# Review project principles
cat .specify/memory/constitution.md

# Create specification
/speckit.specify Add workflow validation to detect security issues

# Create implementation plan  
/speckit.plan Use Go in pkg/workflow/. Follow existing validation patterns. TDD with table-driven tests.

# Generate task breakdown
/speckit.tasks

# Let executor workflow implement (or manual)
/speckit.implement

All documentation follows Astro Starlight format, GitHub Docs voice, and emphasizes constitution-aligned development with TDD principles.

Original prompt

This section details on the original issue you should resolve

<issue_title>[plan] Add spec-kit integration documentation and examples</issue_title>
<issue_description>## Objective

Create comprehensive documentation for the spec-kit integration and provide example specifications that demonstrate the workflow.

Context

Users need to understand how to use spec-kit with gh-aw, including:

  • How to create specifications
  • How to write implementation plans
  • How to define task breakdowns
  • How the automated execution works
  • Best practices and examples

Implementation Steps

  1. Create documentation file docs/src/content/docs/guides/spec-kit-integration.md:

    • Overview of Spec-Driven Development with gh-aw
    • Directory structure explanation
    • Step-by-step guide to creating a specification
    • How the automated workflow works
    • Troubleshooting common issues
  2. Create example specification in .specify/specs/example-feature/:

    • spec.md - Complete feature specification
    • plan.md - Technical implementation plan
    • tasks.md - Task breakdown
    • README explaining the example
  3. Update main README.md:

    • Add section on Spec-Driven Development
    • Link to spec-kit integration documentation
    • Mention the automated execution workflow
  4. Update AGENTS.md:

    • Add spec-kit section to agent instructions
    • Reference .specify/ directory structure
    • Add guidelines for working with specifications
  5. Create tutorial/walkthrough:

    • Step-by-step guide creating a real feature
    • Show how to write constitution principles
    • Demonstrate specification creation
    • Show task breakdown and execution
    • Explain validation and testing

Files to Create/Modify

  • Create: docs/src/content/docs/guides/spec-kit-integration.md
  • Create: .specify/specs/example-feature/spec.md
  • Create: .specify/specs/example-feature/plan.md
  • Create: .specify/specs/example-feature/tasks.md
  • Create: .specify/specs/example-feature/README.md
  • Modify: README.md (add spec-kit section)
  • Modify: AGENTS.md (add spec-kit guidance)

Documentation Outline

spec-kit-integration.md Structure

# Spec-Kit Integration with gh-aw

## What is Spec-Driven Development?

## Getting Started with Spec-Kit

## Directory Structure

## Creating a Specification
- Writing spec.md
- Constitution principles
- User stories and requirements

## Creating an Implementation Plan
- Writing plan.md
- Technical decisions
- Architecture and design

## Task Breakdown
- Writing tasks.md
- Dependency management
- Parallel execution

## Automated Execution
- How the workflow works
- Monitoring execution
- Handling failures

## Best Practices

## Troubleshooting

## Examples

Acceptance Criteria

  • Documentation is comprehensive and clear
  • Example specification is complete and realistic
  • README.md references spec-kit integration
  • AGENTS.md includes spec-kit guidance
  • Tutorial walks through complete workflow
  • Documentation follows Diátaxis framework
  • Code examples are tested and working
  • Links to external spec-kit resources are included

References

AI generated by Plan Command for #5761

Comments on the Issue (you are @copilot in this section)


💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

- Create comprehensive spec-kit integration guide at docs/src/content/docs/guides/spec-kit-integration.md
- Add complete example feature specification in .specify/specs/example-feature/
  - spec.md: Workflow validation report feature specification
  - plan.md: Detailed implementation plan with architecture
  - tasks.md: Task breakdown following TDD principles
  - README.md: Example explanation and usage guide
- Update README.md with Spec-Driven Development section
- Update AGENTS.md with Spec-Kit Integration guidance for AI agents

Addresses issue #5767
Copilot AI changed the title [WIP] Add documentation for spec-kit integration and examples Add spec-kit integration documentation and examples Dec 16, 2025
Copilot AI requested a review from mnkiefer December 16, 2025 07:38
@pelikhan pelikhan closed this Dec 16, 2025
@pelikhan pelikhan deleted the copilot/add-spec-kit-integration-docs branch December 18, 2025 01:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[plan] Add spec-kit integration documentation and examples

3 participants