speckit.specify

Custom agent imported from tangoc2712/data-platform-env (.github/agents/speckit.specify.agent.md). Copyright stays with the author.

User Input

$ARGUMENTS

You MUST consider the user input before proceeding.

Pre-Execution Checks

Check for extension hooks (before specification):

• Check if .specify/extensions.yml exists in the project root.
• If it exists, read it and look for entries under the hooks.before_specify key
• If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally
• Filter out hooks where enabled is explicitly false. Treat hooks without an enabled field as enabled by default.
• For each remaining hook, do not attempt to interpret or evaluate hook condition expressions:
  • If the hook has no condition field, or it is null/empty, treat the hook as executable
  • If the hook defines a non-empty condition, skip the hook and leave condition evaluation to the HookExecutor implementation
• For each executable hook, output the following based on its optional flag:
  • Optional hook (optional: true):

    ## Extension Hooks
    
    **Optional Pre-Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

  • Mandatory hook (optional: false):

    ## Extension Hooks
    
    **Automatic Pre-Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    
    Wait for the result of the hook command before proceeding to the Outline.
    

• If no hooks are registered or .specify/extensions.yml does not exist, skip silently

Outline

Direct interview to create pipeline specification. 8 questions total.

Step 1: Setup

IMPORTANT - Specs Folder Location and Naming Convention:

1. Specs folder location: specs/ is ALWAYS created in the project root (not in .specify/)

   • Example: /my-project/specs/001-pipeline-name/
   • This is stable and consistent across all projects

2. Spec folder naming convention: Spec folders follow a strict naming pattern that MUST match git branch names:

   • Sequential format: ###-short-name (3+ digit prefix)
     • Examples: 001-sales-etl, 002-customer-sync, 123-data-pipeline
     • Prefix increments: 001, 002, 003, ...
   • Timestamp format (alternative): YYYYMMDD-HHMMSS-short-name
     • Examples: 20260321-143022-sales-etl
     • Uses current timestamp when creating spec

3. Git branch naming requirement: Git branches MUST match spec folder prefixes:

   • Sequential: Branch 001-feature-name → Spec folder 001-feature-name/
   • Timestamp: Branch 20260321-143022-feature-name → Spec folder 20260321-143022-feature-name/
   • This allows scripts to find the correct spec folder from the branch name

4. Prefix determination: The prefix is determined by:

   • Check existing specs in specs/ folder
   • Find highest sequential number (001, 002, 003, ...)
   • Increment by 1 for new spec
   • Alternative: Use current timestamp (YYYYMMDD-HHMMSS)

Execution steps:

1. Generate short name from $ARGUMENTS:

   • Extract key words from user input
   • Make it lowercase and URL-safe
   • Keep it short (3-5 words max)
   • Example: "Build daily ETL pipeline to sync sales data" → sales-daily-sync

2. Determine prefix:

   • List existing spec folders in specs/
   • Extract sequential prefixes (001, 002, 003, etc.)
   • Find highest number and increment by 1
   • Example: If specs/ has 001-xxx and 002-yyy, new prefix is 003

3. Create spec directory:

   • Create directory: specs/<prefix>-<short-name>/
   • Example: specs/003-sales-daily-sync/
   • CRITICAL: This is in project root, not in .specify/

4. Copy resolved template:

   • Use template resolution to find the correct spec-template:
     • Bash: TEMPLATE=$(resolve_template "spec-template" "$REPO_ROOT") || true
     • This walks: overrides → presets → extensions → core
     • Ensures data-pipeline preset template is used if installed
   • Copy RESOLVED TEMPLATE to specs/<prefix>-<short-name>/spec.md
   • Set SPEC_FILE path

5. Git branch creation (optional, if using git):

   • If user wants a git branch, create branch matching spec folder name
   • Example: Spec folder 003-sales-daily-sync/ → Branch 003-sales-daily-sync
   • This ensures scripts can find the spec folder from the branch name

Step 2: Direct Interview

Store responses in these variables for template filling:

Q1_RESPONSE = pipeline description
Q2_SOURCE = source system
Q2_LOCATION = source location
Q2_FORMAT = source format
Q2_VOLUME = data volume
Q3_DEST = destination system
Q3_LOCATION = destination location
Q3_FORMAT = destination format
Q3_LOADSTRATEGY = append/upsert/replace
Q4_TRANSFORMS = list of transformations
Q5_FREQUENCY = how often
Q5_TIME = specific time
Q5_SLA = latency requirement
Q6_RETRY = retry strategy
Q6_QUALITY = data quality strategy
Q6_ALERTS = alert method
Q7_DEPS = list of dependencies
Q8_SUCCESS = list of success criteria

═══════════════════════════════════════════════════════════════
  Pipeline Specification Interview
  8 questions total
═══════════════════════════════════════════════════════════════

Question 1/8: Pipeline Description

Describe what this pipeline does.
[1-2 sentences]

Wait for response → Store in Q1_RESPONSE

Question 2/8: Source System

Source system details:

  System: (PostgreSQL/S3/API/Kafka/etc)
  Location: (connection string/path)
  Format: (JSON/CSV/Parquet/Database/etc)
  Volume: (records per day/GB per hour/etc)

Wait for response → Store in Q2_SOURCE, Q2_LOCATION, Q2_FORMAT, Q2_VOLUME

Question 3/8: Destination System

Destination system details:

  System: (Snowflake/S3/PostgreSQL/BigQuery/etc)
  Location: (connection string/path)
  Format: (Parquet/CSV/Database/etc)
  Load strategy: (Append/Upsert/Replace)

Wait for response → Store in Q3_DEST, Q3_LOCATION, Q3_FORMAT, Q3_LOADSTRATEGY

Question 4/8: Transformations

Transformations are operations that change, clean, or enrich data as it moves through the pipeline.

List transformations to apply:

Examples:
  - Filter out invalid/cancelled records
  - Join with reference data (customers, products)
  - Calculate aggregations (sums, averages, counts)
  - Rename/reformat fields
  - Deduplicate records
  - Enrich with API data

Your transformations:
  1. 
  2. 
  3. 
[press Enter on empty line when done]

Wait for response → Store in Q4_TRANSFORMS

Question 5/8: Schedule

Schedule:

  Frequency: (hourly/daily/weekly/event-driven)
  Time: (specific time or cron)
  SLA: (must complete by / latency requirement)

Wait for response → Store in Q5_FREQUENCY, Q5_TIME, Q5_SLA

Question 6/8: Error Handling

On failure:

  Retry strategy: (yes/no - if yes, how many times?)
  Data quality issues: (fail/quarantine/continue)
  Alerts: (email/Slack/PagerDuty)

Wait for response → Store in Q6_RETRY, Q6_QUALITY, Q6_ALERTS

Question 7/8: Dependencies

Dependencies are upstream systems, pipelines, or data sources this pipeline requires before it can run.

List dependencies:

Examples:
  - Upstream pipeline that produces source data
  - External API or service
  - Database or system availability
  - File system or storage location
  - Scheduled job or batch process

Your dependencies:
    1. 
    2. 
  [press Enter on empty line when done]

Wait for response → Store in Q7_DEPS

Question 8/8: Success Criteria

Success criteria are measurable outcomes that indicate the pipeline is working correctly.

List success criteria:

Examples:
  - Pipeline completes by [specific time]
  - Data quality checks pass (> X%)
  - No data loss (record count matches)
  - Latency under [X] minutes/hours
  - Zero failed records
  - Business metric: [specific business outcome]

Your success criteria:
  1. 
  2. 
  3. 
[press Enter on empty line when done]

Wait for response → Store in Q8_SUCCESS

Step 3: Summary

═══════════════════════════════════════════════════════════════
  Specification Summary
═══════════════════════════════════════════════════════════════

Pipeline: {{NAME}}

Source:     {{Q2_SOURCE}} ({{Q2_FORMAT}})
Destination: {{Q3_DEST}} ({{Q3_FORMAT}})
Schedule:   {{Q5_FREQUENCY}} at {{Q5_TIME}}

Transformations: {{count from Q4}}
Error handling: {{Q6_RETRY}}

Success criteria:
  {{first 2 from Q8}}

Smart defaults applied:
  • Retry: 3 times (if not specified)
  • Timeout: 4 hours
  • Quality checks: dedup, null, referential integrity
  • Alert threshold: >5% failure rate

Confirm? (yes/edit)

If "yes": Create specification
If "edit": Ask which section (1-8) to redo

Step 4: Create Specification

IMPORTANT: You must READ and FOLLOW the currently active spec-template.

1. Read the active spec-template:

   • The spec-template is resolved by Spec Kit's template resolution system
   • If data-pipeline preset is installed, it uses: presets/data-pipeline/templates/spec-template.md
   • If no preset, it uses: .specify/templates/spec-template.md (core)
   • YOU MUST READ THE ACTUAL TEMPLATE FILE to see its structure
   • Do NOT assume the structure - READ it from the file
   • Your output MUST follow the exact structure of the resolved template

2. How to find the template:

   • Check if preset is installed: ls .specify/presets/data-pipeline/templates/spec-template.md
   • If exists: Read that file (data-pipeline preset template)
   • If not: Read .specify/templates/spec-template.md (core template)
   • This is how Spec Kit resolves templates at runtime

3. Fill YAML frontmatter:

   pipeline_id: "{{short_name}}"
   status: "defined"
   created_at: "{{current_timestamp}}"
   updated_at: "{{current_timestamp}}"
   author: "{{git_username}}"
   version: 1

4. Fill sections following template structure:

   • Read template to identify exact section names
   • Map responses to template placeholders
   • Use template's markdown structure (tables, lists, etc.)
   • Preserve template's formatting and hierarchy

5. Map responses to template:

   Description section (from template):

   ## Description
   
   {{Q1_RESPONSE}}
   
   **One-line summary**: {{Q2_SOURCE}} → {{Q3_DEST}}

   Data Flow section (from template):

   ## Data Flow
   

   {{Q2_SOURCE}} → {{Q3_DEST}}

   
   | Component | Details |
   |-----------|---------|
   | **Source** | {{Q2_SOURCE}}, {{Q2_LOCATION}}, {{Q2_FORMAT}} |
   | **Destination** | {{Q3_DEST}}, {{Q3_LOCATION}}, {{Q3_FORMAT}} ({{Q3_LOADSTRATEGY}}) |
   | **Frequency** | {{Q5_FREQUENCY}} at {{Q5_TIME}} |
   | **Volume** | {{Q2_VOLUME}} |
   

   Transformations section (from template):

   ## Transformations
   
   {{enumerate Q4_TRANSFORMS}}

   Error Handling section (from template):

   ## Error Handling
   
   | Scenario | Strategy |
   |----------|----------|
   | **Pipeline failure** | {{Q6_RETRY}} |
   | **Data quality issues** | {{Q6_QUALITY}} |
   | **Missing dependencies** | Alert via {{Q6_ALERTS}} |

   Dependencies section (from template):

   ## Dependencies
   
   {{Q7_DEPS}}

   Success Criteria section (from template):

   ## Success Criteria
   
   ✓ {{enumerate Q8_SUCCESS}}

   Notes section (from template):

   ## Notes
   
   SLA: {{Q5_SLA}}
   
   Additional: Include load strategy {{Q3_LOADSTRATEGY}} in implementation

   TODO section (from template):

   ## TODO (Resolve in Planning)
   
   - Detailed schemas for source and destination
   - Specific error handling implementations
   - Monitoring and alerting setup

6. Write to SPEC_FILE following template structure exactly

7. Load constitutions (for validation):

   • Required: Read .specify/memory/constitution.md (base rules)
   • Required: Read .specify/memory/custom-constitution.md (project-specific context - HIGH PRIORITY)
   • Merge rules: Custom constitution overrides base where conflicts exist
   • Apply custom-constitution to validation:
     • Check if specified tools match what's in custom-constitution
     • Validate environment access details are consistent
     • Ensure data formats align with project conventions
   • Combined ruleset: Apply both constitutions together

8. Validate against merged constitution

Step 5: Report Completion

═══════════════════════════════════════════════════════════════
  ✓ Specification created
═══════════════════════════════════════════════════════════════

Spec folder: {{SPEC_FOLDER}}
Spec file: {{SPEC_FILE}}

Location: {{PROJECT_ROOT}}/specs/{{PREFIX}}-{{SHORT_NAME}}/

Spec folder name: {{PREFIX}}-{{SHORT_NAME}}
Git branch name (if using git): {{PREFIX}}-{{SHORT_NAME}}

Next steps:
  1. Review spec: cat {{SPEC_FILE}}
  2. Scan codebase: speckit.scan
  3. Create plan: speckit.plan

Important notes:

• Spec folder location: specs/ is in project root, not in .specify/
• Spec folder name: Follows pattern ###-short-name or YYYYMMDD-HHMMSS-short-name
• Git branch name: Must match spec folder name for scripts to work correctly
• Example: Spec folder specs/003-sales-daily-sync/ → Git branch 003-sales-daily-sync

Post-Execution Checks

Check for extension hooks (after specification):

• Check if .specify/extensions.yml exists
• Look for entries under hooks.after_specify
• Execute or notify based on optional/mandatory flags

Smart Defaults

When not specified:

• Retry: 3 times
• Timeout: 4 hours
• Quality checks: deduplication, null checks, referential integrity
• Alert if: >5% failure rate, data quality issues