Trace2Spec: Augmented Spec-driven development

Boot OpenSpec's Spec-Driven in any project and give superpowers to any coding agent.

This repository contains a comprehensive set of development rules, standards, and AI agent configurations designed to work seamlessly with multiple AI coding copilots. The setup is portable and can be imported into any project to provide consistent, high-quality AI-assisted development.

It's highly recommended to be used along with Spec-Driven Development frameworks like OpenSpec

📁 Repository Structure

.
├── docs/                        # Development standards and specifications
│   ├── base-standards.md        # Core development rules (single source of truth)
│   ├── backend-standards.md
│   ├── frontend-standards.md
│   ├── documentation-standards.md
│   ├── api-spec.yml             # OpenAPI specification
│   ├── data-model.md            # Database and domain models
│   ├── development_guide.md
├── trace2spec/
│   ├── agents/                  # Agent role definitions (backend, frontend, analyst, etc.)
│   └── skills/                  # Reusable skill prompts/workflows
│
├── AGENTS.md                    # Generic agent configuration
├── CLAUDE.md                    # Claude-specific configuration
├── codex.md                     # GitHub Copilot/Codex configuration
└── GEMINI.md                    # Gemini-specific configuration

🤖 Multi-Copilot Support

This repository uses symbolic links or naming conventions to support multiple AI coding copilots without duplication:

• AGENTS.md → Generic agent rules (works with most copilots)
• CLAUDE.md → Optimized for Claude/Cursor
• codex.md → Optimized for GitHub Copilot/Codex
• GEMINI.md → Optimized for Google Gemini

All these files reference the same core rules in docs/base-standards.md, ensuring consistency across different AI tools while allowing copilot-specific customizations.

Why This Approach?

✅ Single Source of Truth: Core rules maintained in one place (base-standards.md)
✅ Copilot Compatibility: Each AI tool finds its configuration using its preferred naming convention
✅ Zero Configuration: Import into a new project and it works immediately
✅ Easy Updates: Update rules once, all copilots benefit
✅ Portable: Copy this structure to any project

🚀 Quick Start

1) Install and Initialize OpenSpec

OpenSpec works great with this repository and is recommended for a spec-driven workflow.

Quick Start requirements from OpenSpec official docs:

• Node.js 20.19.0 or higher

Install OpenSpec globally:

npm install -g @fission-ai/openspec@latest

Then navigate to your project and initialize:

cd your-project
openspec init --tools antigravity

2) Import Into Your Project

Copy this repository into your project first, so the docs/ and trace2spec/ paths already exist when you configure OpenSpec:

# Clone or copy this repository into your project (`-n`: do not overwrite existing files so you keep project's original README)
cp -rn trace2spec/* your-project/

Alternative for step 2 (Claude Code users):

• You can alternatively install the Claude plugin and use it as the coding agent for this import step.
• This only changes how you install Trace2Spec. It does not install OpenSpec, does not update OpenSpec config, and does not customize docs/.

Quick install:

npx trace2spec

This copies all files into your project and recreates the symlink structure automatically. Safe to re-run: existing files are never overwritten.

3) Customize docs/ for Your Project (Mandatory)

This step is required. If you skip it, your AI assistant will use generic technical context instead of your real project context.

Update the files in docs/ to match your stack, architecture patterns, domain language, API contracts, and data model.

For detailed guidance and ready-to-use prompt examples, see Customization.

4) Point OpenSpec Config to Your docs/ and trace2spec/

After openspec init and after copying this repository, update your project's config.yml to include your technical context from docs.

Prompt example to automate this with your copilot:

Update my openspec config.yml context to reference this repository's docs and trace2spec structure.

Requirements:
- Use docs/base-standards.md as the single source of truth.
- Include docs/backend-standards.md, docs/frontend-standards.md, docs/documentation-standards.md.
- Include docs/api-spec.yml, docs/data-model.md, and docs/requirement-traceability-matrix.md.
- Specify that the Stitch MCP must be used for generating and applying UI mockups.
- Tell the agent to adopt trace2spec/agents/backend-developer.md for backend work and trace2spec/agents/frontend-developer.md for frontend work.
- Mention trace2spec/skills as workflow guidance.
- Keep all paths relative to the project root.

Example (config.yml):

context: |
  Tech stack: TypeScript, Node.js, Express, Prisma, Domain-Driven Design (DDD)
  Architecture: Clean Architecture with Domain, Application, and Presentation layers
  We use conventional commits
  Domain: LTI (Leadership. Technology. Impact) ATS platform
  All code, comments, documentation, and technical artifacts must be in English

  Project specs (single source of truth): All artifact creation and implementation MUST follow the project's technical context in trace2spec/. Read and apply these when creating or implementing:
  - docs/base-standards.md — core principles, TDD, language standards, links to backend/frontend/docs standards
  - docs/backend-standards.md — API, database, testing, security (backend changes)
  - docs/frontend-standards.md — React, UI/UX (frontend changes)
  - docs/api-spec.yml — API contracts and endpoint definitions
  - docs/data-model.md — domain and data model
  - docs/documentation-standards.md — docs structure and maintenance
  - docs/requirement-traceability-matrix.md — requirements mapped to Epics, Stories, PRs, and QA tests
  
  Tooling:
  - You MUST use the Stitch MCP for generating and applying UI mockups and design systems when executing UI changes.
  
  For implementation: adopt the relevant agent from trace2spec/agents/ (e.g. backend-developer.md for backend, frontend-developer.md for frontend). Use trace2spec/skills/ for workflow guidance when applicable.

# Per-artifact rules (optional)
# Add custom rules for specific artifacts.
rules:
  # Global: apply trace2spec when creating any artifact
  _global:
    - Before creating any artifact, read and apply docs/base-standards.md
    - For backend-related artifacts, read docs/backend-standards.md and adopt guidelines from trace2spec/agents/backend-developer.md
    - For frontend-related artifacts, read docs/frontend-standards.md and adopt guidelines from trace2spec/agents/frontend-developer.md
    - Use docs/api-spec.yml and docs/data-model.md for API and data consistency in specs and tasks
    - Update docs/requirement-traceability-matrix.md whenever creating or modifying tickets and PRs

✅ Verify Configuration (Required)

Do this after completing the setup steps above.

Your AI copilot should automatically load:

• Claude/Cursor: CLAUDE.md → docs/base-standards.md
• GitHub Copilot: codex.md → docs/base-standards.md
• Gemini: GEMINI.md → docs/base-standards.md

All paths and rules are configured to work seamlessly without manual adjustments.

💡 Usage: Trace2Spec Custom Workflows

The recommended workflow in this repository orchestrates the entire software lifecycle from design to QA using custom commands located in trace2spec/workflows/:

1. /design: Complete software design workflow that generates SRS, Use Cases, Architecture (SDD), UIDD, Epics, QA Test Plans, and the Traceability Matrix.
2. /ui-design: Translates the UIDD, SDD, and Use Cases into visual UI mockups and a formal design system using the Stitch MCP.
3. /plan [JIRA-PROJECT-KEY]: Automates the creation and synchronization of the designed Epics and User Stories to Jira.
4. /refine TICKET-ID: Analyze and enhance user stories with complete, implementation-ready technical detail (including linking UI mockups).
5. /propose [TICKET-ID] & /apply [TICKET-ID]: Use native OpenSpec commands to implement the code per the refined specs.
6. /review [TICKET-ID]: Independent red-team code review before archiving the implementation.
7. /commit: Create focused commit(s) and manage Pull Requests.

After you have implemented all the user stories, run:

8. /test: Executes the Global Release QA Testing phase (E2E with Playwright and Integration with Postman) following the QA Test Plan.

Workflow Reference

flowchart TD
    %% Data Sources / Documents
    REQ[Project Input Notes]
    DOCS[Trace2Spec Artifacts\nSRS, SDD, UIDD, Use Cases, Epics]
    UI[UI Mockups & Design System]
    JIRA[Jira Epics & Stories]
    US[Refined User Story]
    CODE[Code Implementation\nBranch, Tests, Docs]
    PR[Pull Request & Merged]
    QA[QA Testing Report]

    %% Flow
    REQ -- "/design" --> DOCS
    DOCS -- "/ui-design" --> UI
    DOCS -- "/plan" --> JIRA
    JIRA -- "/refine" --> US
    UI -.-> US
    US -- "/propose & /apply" --> CODE
    CODE -- "/review" --> CODE
    CODE -- "/commit" --> PR
    PR -- "/test" --> QA

    %% Aesthetics
    style REQ fill:#f8f9fa,stroke:#343a40,stroke-width:2px,color:#212529
    style DOCS fill:#e2e3e5,stroke:#383d41,stroke-width:2px,color:#383d41
    style UI fill:#d1ecf1,stroke:#17a2b8,stroke-width:2px,color:#0c5460
    style JIRA fill:#fff3cd,stroke:#ffc107,stroke-width:2px,color:#856404
    style US fill:#fff3cd,stroke:#ffc107,stroke-width:2px,color:#856404
    style CODE fill:#d4edda,stroke:#28a745,stroke-width:2px,color:#155724
    style PR fill:#cce5ff,stroke:#007bff,stroke-width:2px,color:#004085
    style QA fill:#f8d7da,stroke:#dc3545,stroke-width:2px,color:#721c24

Required MCP Integrations (Jira + Postman + Playwright)

This workflow is highly integrated with MCP servers to maximize automation:

• Jira MCP (/plan, /refine, /test): Creates epics, updates statuses, and reports bugs automatically.
• Postman MCP (/test): Runs API integration tests.
• Playwright MCP (/test): Runs browser-based E2E journeys.

Recommended installation approach:

• Cursor: enable/configure MCP servers in Cursor settings, providing required credentials like Jira API tokens.
• Other agents/IDEs: follow your tool’s MCP installation docs.

If you don’t use Jira, or you don’t want automated E2E testing in this workflow, just update the workflows and keep using the standard OpenSpec commands.

Example: End-to-End Flow

Use these commands in sequence to take a raw idea to a tested feature:

Optional first step (recommended): create a dedicated worktree before running the command flow, then clean it up when done. The using-git-worktrees skill can automate this.

/design
/plan PROJ
/refine PROJ-10
/propose US-01
/apply US-01
/review US-01
/test 
/commit 

Artifacts are managed through OpenSpec directories during this flow, including testing reports created.

Useful Skills

Skills live in trace2spec/skills/ and are mirrored into .claude/skills/ and .cursor/skills/ via relative symlinks, so any copilot can discover them. The agent loads a skill automatically when a request matches its description (per AGENTS.md §4). The most useful ones in day-to-day work are enrich-us, using-git-worktrees, writing-skills, and code-auditing:

• enrich-us — Analyze and enhance a vague Jira user story (or raw idea) into an implementation-ready ticket with acceptance criteria, technical detail, and edge cases. Use before planning to make sure the team and the AI agree on scope.
• using-git-worktrees — Set up an isolated workspace before starting feature work or executing a plan, with safe creation, baseline checks, copying of local Claude settings, and a complete cleanup workflow when the work is done.
• writing-skills — Author and verify new skills (or refactor existing ones) following TDD-style validation before deployment. Use when adding a skill to trace2spec/skills/ or editing an existing SKILL.md.
• code-auditing — Run a systematic 6-phase code quality audit covering security, performance, type safety, dead code, and library best practices, ending with a prioritized action plan. Use for pre-release reviews, technical-debt sweeps, and dependency audits.

Other active skills in this repository: commit, explain, meta-prompt, update-docs. See each trace2spec/skills/<name>/SKILL.md for the full instructions.

📖 Core Development Rules

All development follows principles defined in docs/base-standards.md:

Key Principles

1. Small Tasks, One at a Time: Baby steps, never skip ahead
2. Test-Driven Development (TDD): Write failing tests first
3. Type Safety: Fully typed code (TypeScript)
4. Clear Naming: Descriptive variables and functions
5. English Only: All code, comments, documentation, and messages in English
6. 90%+ Test Coverage: Comprehensive testing across all layers
7. Incremental Changes: Focused, reviewable modifications

Specific Standards

• Backend Standards: docs/backend-standards.md
  • API development patterns
  • Database best practices
  • Security guidelines
  • Testing requirements
• Frontend Standards: docs/frontend-standards.md
  • React component patterns
  • UI/UX guidelines
  • State management
  • Component testing
• Documentation Standards: docs/documentation-standards.md
  • Technical documentation structure
  • API documentation (OpenAPI)
  • Code documentation
  • Maintenance guidelines

🎯 Benefits

For Developers

• ✅ Consistent Code Quality: AI follows the same standards every time
• ✅ Comprehensive Testing: Automatic 90%+ coverage across all layers
• ✅ Complete Documentation: API specs updated automatically
• ✅ Faster Onboarding: New team members reference the same rules
• ✅ Reduced Review Time: Code follows established patterns

For Teams

• ✅ Copilot Flexibility: Team members can use their preferred AI tool
• ✅ Knowledge Preservation: Standards documented, not in people's heads
• ✅ Quality Consistency: Same standards regardless of who (or what) writes code
• ✅ Easier Code Reviews: Clear expectations and patterns
• ✅ Scalable Practices: Standards scale with the team

For Projects

• ✅ Maintainable Codebase: Clean architecture and clear separation of concerns
• ✅ Production-Ready Code: TDD, error handling, and validation built-in
• ✅ Living Documentation: API specs and data models always current
• ✅ Faster Feature Development: Autonomous AI implementation from plans
• ✅ Lower Technical Debt: Best practices enforced from day one

🔧 Customization

Adapting to Your Project

1. Update technical context: Find the different files in docs and modify core principles, coding standards, business rules and technical documentation to match your needs:

• backend/frontend/testing/documentation standards
• installation guide
• data model
• API docs
• ...

2. Adapt agents in trace2spec/agents: Adjust agent definitions to your project's roles and workflows
3. Extend skills in trace2spec/skills: Define battle-tested prompts and workflows in reusable skills
4. Link Resources: Reference your project's specific documentation or tasks using MCPs
5. Keep the symlink structure: Remember to create relative symlinks from .claude and .cursor to the corresponding trace2spec/agents and trace2spec/skills entries to keep it consistent

Prompt Example: Adapt Technical Context

Use this prompt with your copilot to adapt the docs/ folder while preserving the same baseline structure:

Following the same base structure already present in docs/, update all technical context documents according to this project's specifics.

Requirements:
- Keep the same document set and file names in docs/.
- Replace generic content with this project's real stack, architecture patterns, coding conventions, and domain terminology.
- Update backend, frontend, and documentation standards to reflect actual practices used by this team.
- Update docs/api-spec.yml and docs/data-model.md so they match the real endpoints and entities of this project.
- Ensure all references are internally consistent and aligned across docs/.
- Keep everything in English and make guidance implementation-ready for AI agents.

Maintaining Standards

• Single Source of Truth: Always update base-standards.md first
• Version Control: Track changes to standards like code
• Team Review: Standards changes should be reviewed like pull requests
• Documentation: Keep examples current with actual implementation
• Symlink Integrity: After file renames/moves/suffix changes, verify and update all impacted symlinks
• Canonical Placement: Prefer trace2spec as canonical source and expose through symlinks for .claude/.cursor compatibility

📚 Technical context

Reference Examples

The following files are included as reference examples. You should create your own versions tailored to your specific project:

• API Specification: docs/api-spec.yml (OpenAPI 3.0 format)
  • Create your own API spec documenting your project's endpoints
• Data Models: docs/data-model.md (Database schemas, domain models)
  • Document your database structure and domain entities
• Development Guide: docs/development_guide.md (Setup, workflows)
  • Write setup instructions specific to your tech stack

🤝 Contributing

When contributing to the standards:

1. Update base-standards.md (single source of truth)
2. Test with multiple AI copilots to ensure compatibility
3. Update generated examples in changes/ if needed
4. Document breaking changes clearly
5. Follow the same standards you're defining!

📄 License

Copyright (c) 2026 Licensed under the MIT License

🙏 Acknowledgements

Some workflows and skill patterns in this repository are inspired by the Superpowers framework, especially around:

• using-git-worktrees
• writing-skills

Superpowers project: obra/superpowers

Additional inspiration/source acknowledgements:

• code-auditing skill: inspired by and adapted from jeffrigby/somepulp-agents