Managing Specifications

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.