Create a specification from current conversation context.
Generate a specification from your conversation context, optionally linking it to a GitHub issue. Use this after planning discussions to capture requirements and design decisions. It auto-detects the issue ID from your branch name, or you can specify one manually.
/plugin marketplace add fractary/claude-plugins/plugin install fractary-spec@fractaryCreate a specification from current conversation context.
This command uses the full conversation context as the primary source for generating a specification. Optionally enrich with GitHub issue data by providing --work-id.
Key Features:
--work-id is not provided--force to override)/fractary-spec:create [options]
--work-id <id>: Optional - Link to issue and enrich with issue data (description + all comments). If omitted, automatically detects issue ID from current branch name (e.g., feat/123-description → 123)--template <type>: Optional - Override auto-detection (basic|feature|infrastructure|api|bug)--prompt "<instructions>": Optional - Instructions for how to generate the spec from conversation context--force: Optional - Force creation of a new spec even if one already exists for the issue. Use this when requirements have evolved and you need a new spec.When a spec already exists for an issue, this command will:
WORK-{issue_id}-*.md pattern--force to create additional specsThis makes it safe to embed /fractary-spec:create in workflows without worrying about duplicate specs.
Override with --force:
When you intentionally need multiple specs (e.g., requirements have evolved), use --force:
/fractary-spec:create --work-id 123 --force
This creates an additional spec with a unique slug (timestamp-suffixed if needed).
When --work-id is not provided:
~/.fractary/repo/status-*.cache)issue_id from current branch name--work-idSPEC-{timestamp}-* namingBranch patterns supported (via repo plugin):
feat/123-description → issue #123fix/456-bug-name → issue #456chore/789-task → issue #789{prefix}/{number}-{description} patternAfter a planning discussion in the current session (on main or non-issue branch):
/fractary-spec:create
Generates: /specs/SPEC-20250115143000-<slug>.md
After refining approach while on branch feat/123-user-auth:
/fractary-spec:create
Generates: /specs/WORK-00123-<slug>.md
Note: This is the recommended workflow - branch already indicates the issue, no need to specify --work-id manually.
After refining approach for issue #123:
/fractary-spec:create --work-id 123
Generates: /specs/WORK-00123-<slug>.md
Force specific template type:
/fractary-spec:create --template infrastructure --work-id 123
Generates: /specs/WORK-00123-<slug>.md
Provide explicit instructions alongside conversation:
/fractary-spec:create --prompt "Focus on REST API design with OAuth2" --work-id 123
Generates: /specs/WORK-00123-<slug>.md
--work-id not provided, reads repo plugin cache to detect issue ID from current branch/specs directory
WORK-{id:05d}-{slug}.mdSPEC-{timestamp}-{slug}.mdTemplate is automatically inferred from context:
No prompting required - the best template is selected automatically.
--work-idPattern: WORK-{issue:05d}-{slug}.md
Examples:
WORK-00123-user-authentication.mdWORK-00084-api-redesign.md--work-idPattern: SPEC-{timestamp}-{slug}.md
Examples:
SPEC-20250115143000-user-authentication.mdSPEC-20250115150000-api-redesign.mdTimestamp format: YYYYMMDDHHmmss
🎯 STARTING: Spec Generator (Context Mode)
Template: feature (auto-detected)
───────────────────────────────────────
Analyzing conversation context...
Auto-detecting template: feature
Generating spec: SPEC-20250115143000-user-auth.md
Spec saved locally.
✅ COMPLETED: Spec Generator
Spec created: /specs/SPEC-20250115143000-user-auth.md
Template used: feature
Source: Conversation context
───────────────────────────────────────
Next: Begin implementation using spec as guide
🎯 STARTING: Spec Generator (Context Mode)
Work ID: #123
Template: feature (auto-detected)
───────────────────────────────────────
Analyzing conversation context...
Fetching issue #123 (with comments)...
Merging conversation + issue data...
Auto-detecting template: feature
Generating spec: WORK-00123-user-auth.md
Linking to issue #123...
✅ COMPLETED: Spec Generator
Spec created: /specs/WORK-00123-user-auth.md
Template used: feature
Source: Conversation + Issue #123
GitHub comment: ✓ Added
───────────────────────────────────────
Next: Begin implementation using spec as guide
When --work-id is provided, a comment is added to the issue:
📋 Specification Created
Specification generated for this issue:
- [WORK-00123-user-auth.md](/specs/WORK-00123-user-auth.md)
This spec will guide implementation and be validated before archival.
Why this command bypasses the agent:
Traditional flow:
Command → Agent → Skill
└─ Context lost here (agent starts fresh conversation)
This command:
Command → Skill (direct)
└─ Full conversation context preserved
This design ensures the specification captures the full planning discussion, not just the final command arguments.
In FABER workflow, you can configure which command to use in the Architect phase:
[workflow.architect]
generate_spec = true
spec_plugin = "fractary-spec"
spec_command = "create" # Use context-centric command
After a design discussion with no tied work item:
/fractary-spec:create --template feature
Results in standalone spec for reference.
After extensive planning for issue #123:
/fractary-spec:create --work-id 123
Captures both the planning discussion AND the issue details.
After discussing phase 1 of a complex feature:
/fractary-spec:create --work-id 123 --prompt "Phase 1: User Authentication"
When requirements have evolved and you need an additional spec:
/fractary-spec:create --work-id 123 --force
Creates: /specs/WORK-00123-{new-slug}-{timestamp}.md
Running the command twice on the same issue:
# First run - creates spec
/fractary-spec:create --work-id 123
# Output: Spec created: /specs/WORK-00123-feature-name.md
# Second run - skips creation
/fractary-spec:create --work-id 123
# Output: SKIPPED: Spec already exists
# Existing spec: /specs/WORK-00123-feature-name.md
# Hint: Use --force to create additional spec
Best Practice: Work on issue-tied branches and let auto-detection handle linking:
# 1. Create/checkout issue branch (via repo plugin or manually)
/fractary-repo:branch-create "implement feature" --work-id 123
# 2. Discuss and plan in Claude Code session
# ... conversation about approach, design, requirements ...
# 3. Create spec (auto-detects issue #123 from branch)
/fractary-spec:create
# Result: WORK-00123-implement-feature.md
# - Full conversation context captured
# - Issue data merged automatically
# - GitHub comment added to issue
Override when needed:
--work-id explicitly if you want to link to a different issue--work-id on issue branches if you want standalone specsNo slug generated:
--prompt to provide explicit descriptionTemplate detection unclear:
--template to overrideIssue not found (when using --work-id):
Warning: GitHub comment failed:
Spec creation skipped unexpectedly:
/specs/WORK-{issue_id}-*.md--force flagForce flag not creating unique filename:
WORK-00123-feature-20251205180000.md