Accelerating Portfolio Development with GitHub's Spec-kit and AI Workflows

Creating my portfolio website using GitHub’s Spec-kit

Developer Daveu utilized GitHub’s Spec-kit to streamline the creation of a responsive static portfolio website. The project leveraged a Python-based CLI tool to orchestrate AI-driven development across four distinct feature cycles.

Why This Matters

Spec-kit addresses the friction between rapid AI code generation and structured engineering principles by enforcing a documentation-first workflow. By requiring a constitution and explicit planning phases, it prevents the creation of unmaintainable codebases and ensures that architectural decisions—such as the 2026 requirement for zero user data capture—are strictly followed.

Key Insights

• Persistent CLI installation via uv: The specify-cli can be installed directly from the GitHub repository using the uv tool manager for a stable Python environment.
• The Constitution Command: Using /speckit.constitution establishes core principles that guide all subsequent AI generation, ensuring adherence to constraints like static-only hosting.
• Multi-Model Adaptability: The developer successfully performed feature cycles using both Google Gemini (December 2025) and Anthropic Claude (February 2026) within the same Spec-kit framework.
• Automated Traceability: The tool generates detailed Markdown files, including checklists and requirements.md, to document the AI’s thought process and implementation tasks.
• Decision Record Management: Rather than forcing refactors, Spec-kit allows for documenting deviations from original specs within decision record files after final AI assessments.

Working Examples

Command to persistently install the Spec-kit CLI tool using the uv package manager.

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

Initializes a new project, setting up the AI assistant selection and terminal configuration.

specify init

Practical Applications

• Rapid Prototyping: Use Spec-kit to scaffold static sites for GitHub Pages deployment. Pitfall: Skipping the constitution phase can result in the AI introducing dynamic dependencies that break static hosting.
• Architectural Documentation: Implement the /speckit.plan and /speckit.tasks workflow to automatically generate technical documentation. Pitfall: Making manual code edits without re-syncing with the AI auditor can lead to documentation drift.

References:

• https://github.com/github/spec-kit.git
• https://dev.to/daveu1983/creating-my-portfolio-website-using-githubs-spec-kit-5g40