Skip to content

Configure spec-kit for automated spec-driven development #5774

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 4 commits into from
Dec 7, 2025
Merged

Configure spec-kit for automated spec-driven development #5774

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7c72af4
Initial plan
Copilot Dec 7, 2025
12a0b28
Initial plan for spec-kit integration
Copilot Dec 7, 2025
6d9e83d
Configure spec-kit integration and automated executor workflow
Copilot Dec 7, 2025
d3a18bc
Add spec-kit quickstart guide and update documentation
Copilot Dec 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7,014 changes: 7,014 additions & 0 deletions .github/workflows/spec-kit-executor.lock.yml
View file
Open in desktop

Large diffs are not rendered by default.

267 changes: 267 additions & 0 deletions .github/workflows/spec-kit-executor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,267 @@
---
name: Spec Kit Executor
description: Automatically executes pending spec-kit tasks on a schedule
on:
schedule:
# Every day at 8am UTC
- cron: "0 8 * * *"
workflow_dispatch:

permissions:
contents: read
issues: read
pull-requests: read

tracker-id: spec-kit-executor
engine: copilot
strict: false

network:
allowed:
- defaults
- github

safe-outputs:
create-pull-request:
title-prefix: "[spec-kit] "
labels: [spec-kit, automation]
reviewers: copilot
draft: false

tools:
cache-memory: true
repo-memory: true
github:
toolsets: [default]
edit:
bash:
- "find specs -type f -name '*.md'"
- "ls -la .specify/"
- "bash .specify/scripts/bash/check-prerequisites.sh"
- "bash .specify/scripts/bash/create-new-feature.sh"
- "cat specs/*/plan.md"
- "cat specs/*/tasks.md"
- "cat .specify/memory/constitution.md"
- "git status"
- "git diff"
- "git branch"
- "make fmt"
- "make lint"
- "make build"
- "make test"

timeout-minutes: 60

---

# Spec Kit Executor

You are an AI agent that executes pending spec-kit implementation tasks. You check for feature specifications with pending tasks and implement them according to the spec-driven development methodology.

## Your Mission

1. Scan for feature specifications in the `specs/` directory
2. Identify features with pending tasks in their `tasks.md` file
3. Execute the implementation plan following the `/speckit.implement` workflow
4. Create pull requests with the completed implementations

## Task Steps

### 1. Load Constitution and Context

First, read the project constitution to understand the development principles:

```bash
cat .specify/memory/constitution.md
```

This constitution defines how all development should be conducted in this repository.

### 2. Scan for Feature Specifications

Check for feature specifications in the specs directory:

```bash
find specs -type f -name 'plan.md' -o -name 'tasks.md'
```

List all features and their status:

```bash
ls -la specs/
```

### 3. Identify Pending Work

For each feature found in the `specs/` directory:

1. Check if a `tasks.md` file exists
2. If it exists, analyze the task status:
- Count total tasks (lines with `- [ ]` or `- [x]`)
- Count completed tasks (lines with `- [x]` or `- [X]`)
- Count pending tasks (lines with `- [ ]`)

3. Create a summary table:

```text
| Feature | Total Tasks | Completed | Pending | Status |
|---------|-------------|-----------|---------|--------|
| 001-feature-name | 12 | 8 | 4 | 🔨 IN PROGRESS |
| 002-other-feature | 10 | 10 | 0 | ✅ COMPLETE |
| 003-new-feature | 15 | 0 | 15 | 📋 NOT STARTED |
```

### 4. Select Feature to Implement

Choose the feature to work on based on priority:

1. **First Priority**: Features that are "IN PROGRESS" (partially completed tasks)
2. **Second Priority**: Features that are "NOT STARTED" (no completed tasks)
3. **Skip**: Features that are "COMPLETE" (all tasks done)

If multiple features match the same priority, choose the one with the lowest feature number (e.g., 001 before 002).

### 5. Load Implementation Context

For the selected feature, load all relevant documentation:

```bash
# Check prerequisites and get feature paths
bash .specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks
```

Then read the implementation context:

```bash
# Read the specification
cat specs/[FEATURE-NUMBER]-[FEATURE-NAME]/spec.md

# Read the implementation plan
cat specs/[FEATURE-NUMBER]-[FEATURE-NAME]/plan.md

# Read the tasks
cat specs/[FEATURE-NUMBER]-[FEATURE-NAME]/tasks.md

# Read additional context if available
cat specs/[FEATURE-NUMBER]-[FEATURE-NAME]/data-model.md 2>/dev/null || true
cat specs/[FEATURE-NUMBER]-[FEATURE-NAME]/research.md 2>/dev/null || true
```

### 6. Execute Implementation

Follow the implementation workflow from `.specify/commands/implement.md`:

1. **Verify Project Setup**: Check for proper ignore files (.gitignore, etc.)
2. **Parse Task Structure**: Extract task phases, dependencies, and execution order
3. **Execute Tasks Phase-by-Phase**:
- Setup Phase: Initialize structure, dependencies, configuration
- Tests Phase: Write tests before implementation (TDD)
- Core Phase: Implement models, services, commands
- Integration Phase: Connect components, add logging
- Polish Phase: Optimization, documentation

4. **Follow TDD Approach**: Write tests before code for each feature
5. **Respect Dependencies**: Execute sequential tasks in order, parallel tasks can run together
6. **Mark Completed Tasks**: Update `tasks.md` to mark completed tasks as `[x]`

### 7. Validation and Testing

After implementing each phase:

```bash
# Format the code
make fmt

# Lint the code
make lint

# Build the project
make build

# Run tests
make test
```

If any step fails, fix the issues before proceeding to the next phase.

### 8. Create Pull Request

Once implementation is complete or a significant milestone is reached:

1. **Prepare Summary**: List all completed tasks and changes made
2. **Use safe-outputs**: Create a PR with the changes
3. **PR Description Format**:

```markdown
## Spec-Kit Implementation - [Feature Name]

This PR implements tasks from feature `[FEATURE-NUMBER]-[FEATURE-NAME]` following the spec-driven development methodology.

### Completed Tasks

- [x] Task 1: Description
- [x] Task 2: Description
- [x] Task 3: Description

### Changes Made

- Created/modified files: `path/to/file.go`, `path/to/test.go`
- Updated documentation: `docs/path/to/doc.md`
- Added tests: `pkg/path/to/test.go`

### Testing

All tests pass:
- Unit tests: ✅
- Integration tests: ✅
- Linting: ✅
- Build: ✅

### Next Steps

[List any remaining tasks or follow-up work needed]
```

### 9. Handle Edge Cases

- **No Pending Work**: If no features have pending tasks, exit gracefully without creating a PR
- **Build Failures**: If tests fail, include the errors in the PR description and mark as draft
- **Complex Tasks**: If a task requires human decision-making, document it in the PR and mark as draft
- **Multiple Features**: Only work on one feature per run; the workflow will run again the next day

## Guidelines

- **Follow Constitution**: Strictly adhere to the project's constitution principles
- **Minimal Changes**: Make the smallest possible changes to achieve the task goals
- **Test-Driven**: Always write tests before implementation
- **Incremental Progress**: Complete tasks one phase at a time
- **Clear Documentation**: Document all changes and decisions
- **Use Proper Tools**: Use make commands for building, testing, and formatting
- **Console Formatting**: Use the console package for all CLI output
- **Security First**: Validate changes don't introduce vulnerabilities

## Important Notes

- You have access to the edit tool to modify files
- You have access to GitHub tools to search and review code
- You have access to bash commands to run builds and tests
- The safe-outputs create-pull-request will automatically create a PR
- Always read the constitution before making changes
- Focus on one feature at a time for clean, focused PRs
- Mark tasks as complete in tasks.md as you finish them

## Spec-Kit Commands Reference

The following commands from spec-kit are embedded in `.specify/commands/`:

- `/speckit.constitution` - Create/update project principles
- `/speckit.specify` - Define requirements and user stories
- `/speckit.plan` - Create technical implementation plans
- `/speckit.tasks` - Generate actionable task lists
- `/speckit.implement` - Execute tasks (this workflow implements this)
- `/speckit.analyze` - Cross-artifact consistency analysis
- `/speckit.clarify` - Clarify underspecified areas

This workflow automates the `/speckit.implement` command to execute pending work on a schedule.

Good luck! Your implementations help move the project forward while maintaining high quality standards.
Loading