AI Specs for Skills-First Development

This project is a practical manual and starter kit for running a complete Spec-Driven Development (SDD) workflow with AI, from product requirements and implementation planning to coding, verification, and code review. It provides a skills-first, reusable structure you can copy into your own repository to operationalize SDD in day-to-day delivery.

It is useful because it turns SDD from a high-level idea into a repeatable system with shared standards, canonical prompts, and portable conventions that stay consistent across Codex, Cursor, and Claude.

It is highly recommended to use it with a spec-driven process such as OpenSpec.

If you want to try our best-practices in an Openspec-ready ecosystem, check out our Openspec AI Specs alternative

Repository Structure

.
├── ai-specs/
│   ├── .agents/                 # Canonical agent role definitions
│   ├── .commands/               # Small set of shared utility commands
│   └── skills/                  # Canonical skill definitions (main workflow entrypoint)
│
├── .codex/
│   ├── agents -> ../ai-specs/.agents
│   ├── commands -> ../ai-specs/.commands
│   └── skills -> ../ai-specs/skills
│
├── .cursor/
│   ├── agents -> ../ai-specs/.agents
│   ├── commands -> ../ai-specs/.commands
│   ├── skills -> ../ai-specs/skills
│   └── rules/
│
├── .claude/
│   ├── agents -> ../ai-specs/.agents
│   ├── commands -> ../ai-specs/.commands
│   └── skills -> ../ai-specs/skills
│
├── docs/                        # Project technical context and reference docs
└── README.md

Multi-Copilot Strategy

This repository keeps a single canonical source in ai-specs/ and exposes it to each copilot folder using symlinks:

• .codex/* links to canonical resources
• .cursor/* links to canonical resources
• .claude/* links to canonical resources

Why This Approach

• Single source of truth: one canonical definition for agents, commands, and skills
• No duplicated maintenance: update once, all copilot folders stay aligned
• Tool compatibility: each copilot reads from its expected folder structure
• Safe evolution: workflows can change without reorganizing every tool-specific folder

Skills-First Workflow

Use skills as the default entrypoint for recurring tasks.

Current examples in this repository:

• ai-specs/skills/enrich-user-story/SKILL.md
• ai-specs/skills/write-pr-report/SKILL.md

Commands still exist as lightweight utilities in ai-specs/.commands, but the main functional workflows should be implemented as skills.

Technical Context Location

Project-level technical context now belongs in docs/, for example:

• docs/doc_architecture.md
• docs/doc_ai_planning_mode.md
• docs/doc_verification_guide.md

If you bootstrap this setup into another project, replace these documents with your own architecture, planning, and verification references.

Quick Start

1. Copy this structure into your project.
2. Keep ai-specs/ as canonical.
3. Create symlinks from .codex/, .cursor/, and .claude/ to ai-specs/.
4. Store project context in docs/.
5. Build new reusable workflows as skills under ai-specs/skills/.

Customization Guidelines

• Update agent definitions in ai-specs/.agents/.
• Add or refine skills in ai-specs/skills/.
• Keep commands minimal and only for utility behavior.
• Keep symlinks relative so the repo stays portable.
• Document project-specific technical context in docs/.

Contributing

When contributing:

1. Prefer creating/updating a skill over adding a new command.
2. Keep canonical content inside ai-specs/.
3. Preserve symlink-based sharing across copilot folders.
4. Keep docs/ aligned with the real project state.

Creator

This framework was created by Javier Vargas, Head of AI @ Mapal.

He is the original author of the approach, structure, and workflow design implemented in this repository.

Connect with him on LinkedIn.

License

Copyright © 2026 LIDR.co
Licensed under the MIT License

This repository is part of the AI4Devs program by LIDR.co. Learn more at LIDR.co.