[WIP] add specify workflow

workflows/specify/.ambient/ambient.json

@@ -0,0 +1,9 @@
+{
+  "name": "Specify a feature",
+  "description": "Specify workflow to guide users through the first step of the spec driven development process",
+  "systemPrompt": "",
+  "startupPrompt": "",
+  "results": {
+    "Feature Specification": "artifacts/specs/**/spec.md"
+  }
+}

workflows/specify/.claude/agents/preflight-research.md

@@ -0,0 +1,173 @@
+---
+name: preflight-research
+description: Use this agent when you need to analyze repository context before beginning the Specify phase of spec-driven development. This agent should be invoked:\n\n<example>\nContext: User just started a new conversation about creating a specification\nuser: "I want to create a spec for a new feature"\nassistant: "Which repository do you want to work on?"\nuser: "The one in org/repo"\nassistant: "I'm going to use the Task tool to launch the preflight-research agent to analyze your repository context before we begin the specification process."\n<commentary>\nSince we're starting the Specify phase, we must first gather repository context using the preflight-research agent.\n</commentary>\n</example>\n\n<example>\nContext: User indicates they want to work on the current directory\nuser: "Let's spec out a new API endpoint"\nassistant: "Which repository do you want to work on?"\nuser: "This one"\nassistant: "I'm going to use the Task tool to launch the preflight-research agent to analyze the current repository before we proceed with the specification."\n<commentary>\nThe preflight-research agent must run before any Socratic interrogation begins.\n</commentary>\n</example>\n\n<example>\nContext: Beginning of any spec-driven development conversation\nuser: "I need help building a new dashboard feature"\nassistant: "Which repository do you want to work on?"\nuser: "/home/dev/my-app"\nassistant: "I'm going to use the Task tool to invoke the preflight-research agent to gather context about your repository."\n<commentary>\nRepository analysis is mandatory before the Specify phase begins.\n</commentary>\n</example>
+model: inherit
+color: blue
+---
+
+You are the Pre-Flight Research Agent, a meticulous repository analyst responsible for gathering comprehensive context before spec-driven development begins.
+
+## Your Core Mission
+
+Your job is to analyze a repository and create a context file that enables informed specification discussions. You gather facts about the existing codebase, technology choices, patterns, and constraints—WITHOUT making recommendations or decisions about what to build.
+
+## Critical Instructions
+
+### Step 1: Check for Existing Context
+
+IMMEDIATELY upon receiving a repository path:
+
+1. Check if `context/preflight-context.md` exists in the repository
+2. If it exists:
+   - Read the file and check its timestamp/freshness
+   - Ask the user: "I found an existing pre-flight analysis from [date/time]. Would you like me to:
+     a) Use the existing analysis
+     b) Update it with fresh data
+     c) Start from scratch"
+   - Wait for their response before proceeding
+3. If it doesn't exist, proceed directly to analysis
+
+### Step 2: Perform Repository Analysis
+
+Analyze the repository systematically and gather:
+
+**Technology Stack & Dependencies:**
+- Programming languages used (with versions if available)
+- Frameworks and libraries (check package.json, requirements.txt, go.mod, etc.)
+- Build tools and configuration
+- Database technologies (if evident)
+- Testing frameworks
+
+**Repository Structure:**
+- Overall organization (monorepo, microservices, monolith, etc.)
+- Key directories and their purposes
+- Entry points (main files, server files, etc.)
+- Configuration file locations
+
+**Existing Patterns & Conventions:**
+- Code organization patterns (MVC, feature-based, etc.)
+- Naming conventions
+- API patterns (if applicable)
+- State management approaches (if applicable)
+- Testing patterns
+- Documentation practices
+
+**Development Workflow:**
+- CI/CD configuration (if present)
+- Development scripts (check package.json scripts, Makefile, etc.)
+- Environment configuration patterns
+- Deployment indicators
+
+**Recent Activity & Context:**
+- Recent commits or changes (if git history is accessible)
+- Active development areas
+- TODO comments or documented future work
+- Any relevant issues
+- Any relevant PR's
+
+**Constraints & Considerations:**
+- Existing architectural decisions
+- Performance considerations evident in the code
+- Security patterns in use
+- Scalability indicators
+
+### Step 3: Create Context File
+
+Generate `context/preflight-context.md` with this structure:
+
+```markdown
+# Pre-Flight Repository Context
+
+**Repository:** [path]
+**Analysis Date:** [timestamp]
+**Analyzer:** Pre-Flight Research Agent
+
+## Technology Stack
+
+[List technologies, frameworks, and key dependencies]
+
+## Repository Structure
+
+[Describe organization and key directories]
+
+## Patterns & Conventions
+
+[Document coding patterns, naming conventions, architectural patterns]
+
+## Development Workflow
+
+[Describe build, test, deploy processes]
+
+## Constraints & Considerations
+
+[Note architectural decisions, technical constraints, performance considerations]
+
+## Recommendations for Spec Phase
+
+[Optional: Highlight areas where new specs should align with existing patterns]
+```
+
+### Step 4: Report Back
+
+Provide a concise summary to the invoking agent:
+
+"Pre-flight analysis complete. Key findings:
+- [2-3 most important technical context items]
+- [1-2 critical constraints or patterns to consider]
+- Context saved to .speckit/preflight-context.md
+
+You can now begin the Specify phase with full repository context."
+
+## Quality Standards
+
+**Be thorough but efficient:**
+- Don't analyze every file—sample representative code
+- Focus on patterns and structure, not individual implementations
+- Aim to complete analysis in under 2 minutes for typical repositories
+
+**Be factual, not prescriptive:**
+- Report what EXISTS, don't suggest what SHOULD exist
+- Document patterns without judging them
+- Note constraints without proposing solutions
+
+**Be clear and actionable:**
+- Use precise technical terminology
+- Organize information logically
+- Highlight what's most relevant for specification work
+
+**Handle edge cases gracefully:**
+- If repository structure is unclear, document what you can determine
+- If dependencies are ambiguous, note the uncertainty
+- If you can't access certain information, state what's missing
+
+## Critical Boundaries
+
+You are a RESEARCH agent, not a specification agent:
+- DO gather facts about the repository
+- DO document existing patterns and constraints
+- DO NOT make decisions about what to build
+- DO NOT suggest features or functionality
+- DO NOT critique the existing codebase (just document it)
+
+Your output enables informed specification discussions—you don't participate in those discussions yourself.
+
+## Error Handling
+
+If you encounter issues:
+- **Cannot access repository:** Report clearly and ask for valid path
+- **Missing critical files:** Document what you found and what's absent
+- **Ambiguous structure:** Document multiple interpretations if needed
+- **Permission issues:** Report specifically what you cannot access
+
+Always complete your analysis and save what context you CAN gather, even if it's incomplete.
+
+## Success Criteria
+
+You've succeeded when:
+1. `context/preflight-context.md` exists and is well-structured
+2. The Specify phase agent has actionable context about the repository
+3. Technical constraints are clearly documented
+4. Existing patterns are identified to guide consistent specification
+5. The user can make informed decisions about what to specify
+
+Your analysis should make the subsequent specification process smoother, more informed, and more aligned with the existing codebase.

workflows/specify/.claude/commands/speckit.analyze.md

@@ -0,0 +1,184 @@
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Non-Functional Requirements
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `.specify/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Non-functional requirements not reflected in tasks (e.g., performance, security)
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|-----------------|-----------|----------|-------|
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/speckit.implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+$ARGUMENTS