Incorporate documents into an existing or new workflow and advance stages intelligently
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
Incorporate external documents (specs, plans, research, checklists, etc.) into existing workflows or initiate new workflows using the document as context. This command intelligently:
/speckit.analyze for intelligent incorporation/speckit.workflows.incorporate <document-path> [--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 changesFirst, 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 branchFEATURE_DIR - Feature directory path (if in workflow)FEATURE_SPEC - Main specification fileIMPL_PLAN - Implementation plan fileTASKS - Task list fileDetermine workflow stage:
FEATURE_DIR not found -> Not in workflowUse native spec-kit analyze to understand the document:
/speckit.analyze <document-path>
From the analysis, identify:
Document Type - What kind of document is this?
Key Content Areas - Main sections and topics covered
Completeness - Is it comprehensive or partial?
Conflicts - Does it contradict existing workflow docs?
Detection Patterns:
Based on workflow context and document type, choose strategy:
Action: Initiate Workflow
If --workflow specified, use that. Otherwise, determine from document content/type:
Save the document to a temporary location, with appropriate naming (e.g., spec.md, bugfix.md, plan.md etc.)
Execute the appropriate handoff to create the workflow:
/speckit.specify or /speckit.enhance/speckit.bugfix or /speckit.hotfix/speckit.refactor/speckit.deprecate/speckit.baselineAction: Enrich Current Stage
Append or merge document content into existing stage document.
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
Action: Create Intermediate Stages, Then Advance
Example: Have spec only, document is tasks
First, create minimal plan:
/speckit.plan
Then, create tasks using document:
/speckit.tasks
Action: Enrich Most Relevant Stage Document
Research and checklists are supplementary - don't advance stages, just enrich:
When incorporating document content:
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)"
If analyze indicates overlapping content:
When adding to existing docs:
<!-- Incorporated from: document-name.md -->Before making changes:
# Ensure changes are trackable
git diff --exit-code || echo "Uncommitted changes exist"
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)
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: Document not found: nonexistent.md
Please check the path and try again.
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 - 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)
/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 stageNote: This is a command extension - it doesn't create workflow structures itself, but works with existing workflows and delegates to appropriate workflow commands/scripts.