ent-workflow
OpenSpec workflow and task delegation patterns. Spec-driven development with artifact creation, task tracking, and validation.
SKILL.mdpkg/skills/ent/ent-workflow/SKILL.md
GitHubRole
Guide through OpenSpec CLI workflows and proper task delegation patterns using the Task tool.
OpenSpec CLI Workflow
OpenSpec uses artifacts to structure work:
- proposal.md - What and why (requirements, scope, approach)
- tasks.md - Implementation checklist
- specs/ - Delta specs (changes to main specs)
- implementation - The actual code
Always use the openspec CLI via Bash, not MCP tools.
Creating Changes
# Initialize OpenSpec in a project (if needed)
openspec init
# Create a new change
openspec new change add-feature-name
# Fast-forward: create all artifacts in one go
# This creates proposal.md, tasks.md, and any needed specs
openspec ff add-feature-name
# OR: Incremental artifact creation
openspec continue add-feature-name # Creates next artifact
Working with Artifacts
# Show change status and artifacts
openspec show add-feature-name
# Show specific artifact
openspec show add-feature-name --artifact proposal
openspec show add-feature-name --artifact tasks
# Get instructions for creating next artifact
openspec instructions add-feature-name
# Validate change structure
openspec validate add-feature-name
Viewing Changes
# List all active changes
openspec list
# List specs
openspec list --specs
# Show change with all artifacts
openspec show add-feature-name --format markdown
# Check artifact completion status
openspec status add-feature-name
Implementation
# Task implementation is guided by tasks.md
# After implementation, sync delta specs to main specs
openspec sync add-feature-name
Archiving
# Verify before archive (checks all artifacts exist and are valid)
openspec validate add-feature-name
# Archive completed change
openspec archive add-feature-name
Schema Management
# List available workflow schemas
openspec schemas
# Show template paths for a schema
openspec templates --schema default
Workflow Patterns
Pattern 1: Quick Feature (Fast-Forward)
# 1. Create change and all artifacts at once
openspec new change add-login-validation
openspec ff add-login-validation
# 2. Review generated artifacts
openspec show add-login-validation
# 3. Implement tasks from tasks.md
# 4. Archive when done
openspec archive add-login-validation
Pattern 2: Incremental (Step-by-Step)
# 1. Create change directory
openspec new change refactor-auth
# 2. Create proposal first
openspec continue refactor-auth
# 3. Create tasks
openspec continue refactor-auth
# 4. Create specs if needed
openspec continue refactor-auth
# 5. Implement
# 6. Archive
openspec archive refactor-auth
Pattern 3: Spec Updates
# 1. Create change for spec updates
openspec new change update-api-spec
# 2. Fast-forward to create artifacts
openspec ff update-api-spec
# 3. Edit delta specs in openspec/changes/update-api-spec/specs/
# 4. Sync to main specs
openspec sync update-api-spec
# 5. Archive
openspec archive update-api-spec
Task Delegation Patterns
Most work should happen inline in the main conversation, where skills auto-activate. Spawn subagents via the Task tool when context isolation, parallel work, or a different model tier is needed.
When to Delegate to Subagents
- Context isolation — verbose output (large codegen, deep search) that would pollute main context
- Parallel work — multiple independent tasks can run simultaneously
- Different model tier — task needs opus reasoning or haiku speed
- Tool restrictions — read-only exploration (use Explore agent type)
Delegation by Task Type
| Task Type | Approach | If Subagent: Model + Type |
|---|---|---|
| Write/modify code | Inline (skills auto-activate) | sonnet, general-purpose |
| Design architecture | Inline or subagent for isolation | opus, general-purpose |
| Break feature into tasks | Inline | sonnet, general-purpose |
| Quick triage | Inline | haiku, Explore |
| Fix a bug | Inline (debug-core skill activates) | sonnet, general-purpose |
| Debug concurrency/perf | Inline or subagent | opus, general-purpose |
| Write/fix tests | Inline (go-test skill activates) | sonnet, general-purpose |
| Review code | Subagent (read-only) | opus, Explore |
| Code investigation | Subagent (read-only) | haiku/sonnet, Explore |
| Verify requirements | Subagent (read-only) | opus, Explore |
Subagent Invocation Examples
# Read-only exploration
Task(model: "haiku", subagent_type: "Explore", prompt: "...")
# Standard implementation
Task(model: "sonnet", subagent_type: "general-purpose", prompt: "...")
# Deep analysis or review
Task(model: "opus", subagent_type: "Explore", prompt: "...")
Safety Checkpoints
Before irreversible operations:
- Verify backups exist
- Confirm user intent for destructive ops
- Run validation before deployment
- Test rollback procedures
- Document decision and reasoning
Common Pitfalls
OpenSpec
- Don't duplicate OpenSpec functionality - Always use
openspecCLI - Don't skip validation - Always run
openspec validatebefore archiving - Don't manually move archives - Use
openspec archive - Don't forget to sync specs - Use
openspec syncto update main specs
Delegation
- Don't over-delegate - Prefer inline work; subagents cost ~4x more tokens
- Don't skip handoff context - When delegating, include clear requirements
- Don't assume state - Always verify current state before acting
- Don't ignore blockers - Escalate promptly when stuck
Examples
OpenSpec Workflow
<example> <input>Create a new change for adding user authentication</input> <output> I'll create a new OpenSpec change for user authentication:openspec new change add-user-authentication
Now I'll fast-forward to create all artifacts:
openspec ff add-user-authentication
This creates:
openspec/changes/add-user-authentication/proposal.mdopenspec/changes/add-user-authentication/tasks.md- Any needed specs in
openspec/changes/add-user-authentication/specs/
Let me show the current status:
openspec show add-user-authentication
</output>
</example>
<example>
<input>What's the status of my current changes?</input>
<output>
Let me list all active changes:
openspec list
To see artifact completion status for a specific change:
openspec status change-name
</output>
</example>
References
- OpenSpec CLI:
openspec --help - Change commands:
openspec change --help - Artifact workflow:
openspec instructions --help - Schemas:
openspec schemas