gh-jeanluciano-quaestor-src-quaestor/skills/managing-specifications/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
Managing Specifications	Create, manage, and track specifications through their full lifecycle from draft to completion. Use when user wants to plan features, create specs, check progress, activate work, or complete specifications.	Write Read Edit Bash Glob Grep

Managing Specifications

I help you work with specifications: creating new specs from requirements, managing their lifecycle (draft → active → completed), and tracking progress automatically.

When to Use Me

Auto-activate when:

• Invoked via /quaestor:plan slash command
• User describes a feature with details: "I want to add user authentication with JWT tokens"
• User explicitly requests spec creation: "Create a spec for X", "Write a specification for Y"
• User asks about spec status: "What specs are active?", "Show spec progress"
• User wants to activate work: "Start working on spec-feature-001"
• User wants to complete: "Mark spec-feature-001 as done"
• User checks progress: "How's the authentication feature going?"

Do NOT auto-activate when:

• User says only "plan" or "plan it" (slash command handles this)
• User is making general requests without specification context
• Request needs more clarification before creating a spec

Quick Start

New to specs? Just describe what you want to build:

"I want to add email notifications when orders are placed"

I'll ask a few questions, then create a complete specification for you.

Have specs already? Tell me what you need:

"Show me my active specs"
"Activate spec-feature-003"
"What's the progress on spec-auth-001?"

How I Work

I detect what you need and adapt automatically:

Mode 1: Creating Specifications

When you describe a feature or ask me to create a spec, I:

1. Ask clarifying questions (if needed)
2. Generate a unique spec ID (e.g., spec-feature-001)
3. Create .quaestor/specs/draft/[spec-id].md
4. Report next steps

See @WRITING.md for the complete specification template and writing process

Mode 2: Managing Lifecycle

When you ask about spec status or want to move specs, I:

1. Check current state (scan all folders)
2. Perform the requested action (activate, complete, show status)
3. Update spec metadata automatically
4. Report changes

See @LIFECYCLE.md for folder-based lifecycle management and progress tracking

The 3-Folder System

Specifications live in folders that represent their state:

.quaestor/specs/
├── draft/              # New specs (unlimited)
├── active/             # Work in progress (MAX 3)
└── completed/          # Finished work (archived)

The folder IS the state - no complex tracking needed!

Why max 3 active? Forces focus on finishing work before starting new features.

Progressive Workflows

I provide just enough information for your current task, with details available when needed:

Creating Your First Spec

Minimal workflow (I guide you):

You: "Add user authentication"
Me: I'll ask 3-5 questions
Me: Create spec-feature-001.md in draft/

Managing Existing Specs

Common operations:

• "Show active specs" → List with progress bars
• "Activate spec-feature-003" → Move draft/ → active/
• "Complete spec-auth-001" → Move active/ → completed/

Deep Dive Available

When you need more details:

• @WRITING.md - Complete template, field descriptions, examples
• @LIFECYCLE.md - All lifecycle operations, validation rules, batch operations
• @TEMPLATE.md - Field-by-field guide to spec structure

Key Features

Smart Spec Creation

✅ Auto-generate unique IDs ✅ Forgiving template (auto-corrects common mistakes) ✅ No placeholders - only real values ✅ Rich metadata (priority, type, timestamps)

Automatic Lifecycle Management

✅ Folder-based states (simple and visual) ✅ 3-active-spec limit (enforced automatically) ✅ Progress calculation from checkboxes ✅ Metadata updates on state changes

Progress Tracking

✅ Parse checkbox completion: - [x] vs - [ ] ✅ Calculate percentage: 4/5 complete = 80% ✅ Visual progress bars ✅ Branch linking support

Success Criteria

Creating specs:

• ✅ Spec has unique ID and proper frontmatter
• ✅ All fields have actual values (no placeholders)
• ✅ Acceptance criteria defined with checkboxes
• ✅ Saved to .quaestor/specs/draft/[spec-id].md

Managing specs:

• ✅ State transitions work correctly (draft → active → completed)
• ✅ 3-active limit enforced
• ✅ Progress calculated accurately from checkboxes
• ✅ Metadata updates automatically

Next Steps After Using This Skill

Once you have specifications:

1. Activate a spec: "Activate spec-feature-001"
2. Implement it: Use /impl spec-feature-001 or implementing-features skill
3. Track progress: "What's the status?" or "Show active specs"
4. Complete it: "Complete spec-feature-001" when all criteria checked
5. Ship it: Use reviewing-and-shipping skill to create PR

---

I handle both creation and management of specifications. Just tell me what you need - I'll detect the mode and guide you through it with minimal upfront context.