Speckit Workflows Incorporate

Speckit Workflows.Incorporate Skill

The user input to you can be provided directly by the agent or as a command argument - you MUST consider it before proceeding with the prompt (if not empty).

User input:

$ARGUMENTS

Overview

Incorporate external documents (specs, plans, research, checklists, etc.) into existing workflows or initiate new workflows using the document as context. This command intelligently:

1. Detects document type - Identifies what kind of document it is
2. Detects workflow context - Determines if you're in a workflow and at what stage
3. Advances workflow stages - Automatically progresses to appropriate stage
4. Leverages analysis - Uses /speckit.analyze for intelligent incorporation

Usage

/speckit.workflows.incorporate  [--type TYPE] [--workflow WORKFLOW] [--stage STAGE] [--enrich] [--dry-run]

Options:

• --type TYPE - Force document type (spec|plan|tasks|research|checklist|postmortem)
• --workflow WORKFLOW - Initiate specific workflow if not in one (baseline|bugfix|enhance|modify|refactor|hotfix|deprecate|cleanup)
• --stage STAGE - Target stage (auto|current|spec|plan|tasks)
• --enrich - Enrich current stage docs instead of advancing (default for research)
• --dry-run - Show what would be done without making changes

Step 1: Load Workflow Context

First, get current workflow context:

cd "$(git rev-parse --show-toplevel)" && \
source .specify/scripts/bash/common.sh && \
CURRENT_BRANCH=$(get_current_branch) && \
echo "Current branch: $CURRENT_BRANCH" && \
get_feature_paths

This provides:

• CURRENT_BRANCH - Current git branch
• FEATURE_DIR - Feature directory path (if in workflow)
• FEATURE_SPEC - Main specification file
• IMPL_PLAN - Implementation plan file
• TASKS - Task list file

Determine workflow stage:

• If FEATURE_DIR not found -> Not in workflow
• If only spec exists -> Spec stage
• If spec + plan exist -> Planning stage
• If spec + plan + tasks exist -> Task stage

Step 2: Analyze the Document

Use native spec-kit analyze to understand the document:

/speckit.analyze 

From the analysis, identify:

1. Document Type - What kind of document is this?

• Spec/Requirements - Goals, acceptance criteria, architecture
• Plan/Approach - Implementation steps, technical decisions
• Tasks - Concrete action items, checklist format
• Research - Background info, API docs, examples, findings
• Checklist - Validation items, testing scenarios
• Post-mortem - Incident analysis, lessons learned

1. Key Content Areas - Main sections and topics covered

1. Completeness - Is it comprehensive or partial?

1. Conflicts - Does it contradict existing workflow docs?

Detection Patterns:

• Spec indicators: "Requirements", "Goals", "Acceptance Criteria", "Architecture", "User Stories"
• Plan indicators: "Implementation", "Approach", "Technical Design", "Steps", "Strategy"
• Tasks indicators: Checkbox lists, numbered action items, "TODO", "Task", specific assignments
• Research indicators: "Background", "Investigation", "Findings", "Documentation", external links
• Checklist indicators: Validation lists, test scenarios, "Verify", "Ensure", "Check"

Step 3: Determine Action Strategy

Based on workflow context and document type, choose strategy:

Scenario A: Not in Workflow (No FEATURE_DIR)

Action: Initiate Workflow

1. If --workflow specified, use that. Otherwise, determine from document content/type:

• If the document is a plan, task list or both:
• Contains "enhance", "feature", "improvement" or refers to new functionality -> enhance
• Contains "bug", "fix", "regression" or refers to an issue with existing functionality -> hotfix
• If the document is a spec:
• Contains "feature", "enhance", "improvement" or refers to new functionality -> feature or enhancement depending on complexity
• Contains "refactor", "cleanup", "optimize" -> refactor
• Contains "deprecate", "remove", "sunset" -> deprecate (ask user which feature to deprecate if unclear)
• Contains "baseline", "context", "current state" -> baseline
• Contains "bug", "fix", "regression" -> bugfix or hotfix depending on complexity
• Otherwise -> Ask user for workflow type

1. Save the document to a temporary location, with appropriate naming (e.g., spec.md, bugfix.md, plan.md etc.)

1. Execute the appropriate handoff to create the workflow:

• For feature/enhancement: /speckit.specify or /speckit.enhance
• For bugfix/hotfix: /speckit.bugfix or /speckit.hotfix
• For refactor: /speckit.refactor
• For deprecate: /speckit.deprecate
• For baseline: /speckit.baseline

Scenario B: Currently in Workflow - Document Type Matches Current Stage

Action: Enrich Current Stage

Append or merge document content into existing stage document.

Scenario C: Current in Workflow - Document Type is Next Stage

Action: Advance to Next Stage

C1: Have spec, document is plan

/speckit.plan
# Then incorporate plan content into plan.md

C2: Have spec + plan, document is tasks

/speckit.tasks
# Then incorporate task content into tasks.md

Scenario D: Current in Workflow - Document Type Skips Stages

Action: Create Intermediate Stages, Then Advance

Example: Have spec only, document is tasks

1. First, create minimal plan:

``bash /speckit.plan ``

1. Then, create tasks using document:

``bash /speckit.tasks ``

Scenario E: Document Type is Research/Checklist

Action: Enrich Most Relevant Stage Document

Research and checklists are supplementary - don't advance stages, just enrich:

• Research -> Add to spec.md (background section) or plan.md (approach section)
• Checklist -> Add to tasks.md (validation section) or create separate checklist.md

Step 4: Intelligent Incorporation

When incorporating document content:

4.1 Check for Conflicts

Compare document with existing content:

# If conflicts detected by analyze
# Present to user:
echo "Potential conflicts detected:"
echo "  - Document says X"
echo "  - Existing spec says Y"
echo ""
echo "Options:"
echo "  1. Keep existing (skip conflicting parts)"
echo "  2. Replace with new (update existing)"
echo "  3. Mark as NEEDS RECONCILIATION (both present)"

4.2 Detect Duplicates

If analyze indicates overlapping content:

• Skip truly duplicate content
• Merge complementary information
• Note: "Incorporated X from document, skipped Y (already covered)"

4.3 Structure Content

When adding to existing docs:

• Maintain document structure (use existing headers)
• Add new sections if needed
• Preserve formatting consistency
• Add source attribution: ``

4.4 Preserve Git History

Before making changes:

# Ensure changes are trackable
git diff --exit-code || echo "Uncommitted changes exist"

Step 5: Provide Feedback

Clearly summarize what was done:

Incorporated document: research-notes.md

Actions taken:
  - Detected document type: Research
  - Current workflow: bugfix/001-login-error
  - Current stage: Spec
  - Action: Enriched bug-report.md with research findings

Added sections:
  - Background on authentication flow
  - API documentation excerpts
  - Similar bug references

Next steps:
  - Review incorporated content in bug-report.md
  - Run: /speckit.plan (when ready to move to planning)

Step 6: Suggest Next Actions

Based on workflow state after incorporation:

Workflow Progress:
  [done] Spec      - bug-report.md (enriched)
  [ ] Plan      - Ready to create with: /speckit.plan
  [ ] Tasks     - Awaiting plan completion

Suggested: Review the enriched spec, then run /speckit.plan to continue.

Error Handling

Document Not Found

Error: Document not found: nonexistent.md
Please check the path and try again.

Cannot Determine Workflow Type

Cannot determine appropriate workflow type from document.
Please specify: /speckit.workflows.incorporate document.md --workflow [type]

Available workflows:
  baseline, bugfix, enhance, modify, refactor, hotfix, deprecate, cleanup

Conflicts Detected

Conflicts detected - user input required
Cannot auto-merge due to contradictions.

Please resolve manually or use:
  --force-append  (add as-is with conflict marker)
  --skip-conflicts (skip conflicting sections)

Best Practices

1. Use analyze first for unfamiliar documents
2. Review enriched docs before advancing stages
3. Commit after incorporation to preserve history
4. Use --dry-run for complex incorporations
5. Specify --type if detection might be ambiguous
6. Keep original documents (don't delete after incorporation)

Integration with Other Commands

• /speckit.analyze - Review after incorporation to address conflicts or inconsistencies
• /speckit.plan - Called automatically when advancing to plan stage
• /speckit.tasks - Called automatically when advancing to tasks stage
• Workflow creation scripts - Called when initiating new workflows

---

Note: This is a command extension - it doesn't create workflow structures itself, but works with existing workflows and delegates to appropriate workflow commands/scripts.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pradeepmouli
• Source: pradeepmouli/skillit
• License: MIT
• Homepage: https://pradeepmouli.github.io/skillit/

Install and usage instructions live in the source repository linked above.