[Preset]: Add workflow-preset

[bigsmartben]

Preset ID

workflow-preset

Preset Name

Workflow Preset

Version

1.0.3

Description

Adds design-aware planning artifacts and agent-native implementation handoff orchestration for larger Spec Kit features.

The preset keeps /speckit.plan and /speckit.tasks compatible with the core workflow while adding stable homes for object design, service sequencing, and test planning. It replaces /speckit.implement with a Core Agent, Vertical Planner Agent, and Worker Agent handoff contract so implementation can be executed in scoped worker contexts instead of one overloaded implementation prompt.

Author

bigsmartben

Repository URL

https://github.com/bigsmartben/spec-kit-workflow-preset

Download URL

https://github.com/bigsmartben/spec-kit-workflow-preset/archive/refs/tags/v1.0.3.zip

Release URL

https://github.com/bigsmartben/spec-kit-workflow-preset/releases/tag/v1.0.3

License

MIT

Required Spec Kit Version

=0.8.10.dev0

Required Extensions

None

Templates Provided

• templates/plan-template.md - adds design artifact navigation to the plan template
• schemas/speckit.implement.manifest.v1.schema.json - manifest contract for implementation handoff runs
• schemas/speckit.implement.handoff.v2.schema.json - worker handoff contract
• schemas/speckit.implement.receipt.v1.schema.json - worker receipt contract

Commands Provided

• commands/speckit.plan.md - wraps core planning with optional class, sequence, and test design artifacts
• commands/speckit.tasks.md - wraps task generation with optional design artifact awareness
• commands/speckit.implement.md - runs agent-native handoff orchestration or executes exactly one worker handoff

Number of Scripts

0

Tags

planning, design, implementation, orchestration, handoff

Main Capability Areas

Plan enhancement

• Adds class-diagram.md for internal object design: classes, interfaces, abstract types, services, repositories, adapters, factories, strategies, controllers, coordinators, composition, dependency direction, and design pattern participants.
• Adds contracts/sequences.md for service and interaction flow: API calls, commands, events, async workers, external systems, retries, compensation, rollback, and failure branches.
• Adds test-plan.md for validation design: test objectives, in/out of scope, test levels, data strategy, requirement traceability, and scenario matrix.
• Keeps canonical Spec Kit boundaries intact: product requirements stay in spec.md, domain model details stay in data-model.md, interface schemas stay in contracts/, and executable validation guidance stays in quickstart.md.

Task generation enhancement

• Lets /speckit.tasks consume the planning artifacts when present.
• Uses object design, service sequence, and test-plan constraints to derive implementation, integration, orchestration, failure-handling, and validation tasks.
• Preserves the existing checklist format and user-story organization.

Implementation handoff orchestration

• Replaces broad /speckit.implement execution with agent-native handoff orchestration.
• Core Agent owns lifecycle state, context-index.json, final handoff-manifest.json, worker dispatch, receipt review, tasks.md status commits, integration verification, and closeout.
• Vertical Planner Agents each plan one vertical_capability, create shard plans, draft handoffs, draft context digests, and derive allowed read/write paths.
• Worker Agents execute exactly one persisted speckit.implement.handoff.v2 handoff and write one speckit.implement.receipt.v1 receipt.
• Handoffs record lifecycle stage, vertical capability, capability boundary, planner outputs, draft source, assigned task IDs, context digest path, allowed paths, validation commands, and forbidden actions.

Context Load / Reasoning Drift Mitigation

The preset is intended to reduce implementation-stage context overload, where a single agent run must keep product requirements, technical decisions, object design, service flows, test strategy, task ordering, and current code edits in one prompt. That load can cause reasoning drift: losing earlier design decisions, blurring task boundaries, reading unrelated documents, editing the wrong files, or marking tasks complete without enough validation evidence.

This preset mitigates that by:

• Giving object design, sequence flow, and validation intent stable planning artifacts before tasks are generated.
• Creating context-index.json so planning context is indexed without requiring every worker to read every source document.
• Giving Worker Agents compact context digests instead of the full planning corpus.
• Recording unresolved required context as context_gaps; workers must stop rather than guess or expand context on their own.
• Restricting workers to allowed_read_paths and allowed_write_paths.
• Keeping tasks.md writes centralized in the Core Agent after receipt review.

Testing Checklist

• Preset installs successfully via specify preset add
• Template resolution works correctly after installation
• Documentation is complete and accurate
• Tested on at least one real project

Submission Requirements

• Valid preset.yml manifest included
• README.md with description and usage instructions
• LICENSE file included
• GitHub release created with version tag
• Preset ID follows naming conventions (lowercase-with-hyphens)

Verification Performed

• python3 -m unittest tests/test_preset_contract.py in the preset repository: 36 passed
• git diff --check: passed
• GitHub Release v1.0.3 is published and is not draft/prerelease: https://github.com/bigsmartben/spec-kit-workflow-preset/releases/tag/v1.0.3
• Fresh Spec Kit project install from https://github.com/bigsmartben/spec-kit-workflow-preset/archive/refs/tags/v1.0.3.zip: installed Workflow Preset v1.0.3 successfully
• specify preset info workflow-preset: confirmed metadata, tags, 7 provided template/command entries, repository, license, and installed status

Related

Earlier catalog PRs were closed because community preset submissions are issue-first:

• Add workflow-preset to community catalog #2617
• Add Workflow Preset to community catalog #2641

[bigsmartben]

Review update: I fixed a macOS path normalization issue in the preset repository after submission.\n\nCommit: bigsmartben/spec-kit-workflow-preset@868c3fe\n\nThe fix keeps shard scope verification consistent when temporary directories resolve through paths like /var -> /private/var. Contract tests pass locally with the existing test suite:\n\n\n/tmp/spec-kit-workflow-preset-venv/bin/python -m unittest tests/test_preset_contract.py\nRan 11 tests\nOK\n\n\nI am leaving the release version/tag unchanged for now during review, and can publish a follow-up patch release if the listing review requires the downloadable archive to include this fix.

[bigsmartben]

Update for the workflow-preset submission after follow-up hardening work.

Repository commit now pushed to main:
bigsmartben/spec-kit-workflow-preset@a2dddef

What changed since the original submission:

• /speckit.implement now invokes the preset orchestrator script directly instead of going through specify workflow run, avoiding the workflow shell step's fixed timeout for long sequential shard runs.
• Shard CLI stdout/stderr is received by a script-level log receiver and written to per-shard log files instead of being streamed into the main agent transcript.
• Final dispatch output is compacted: successful shards keep log paths and status only; failed shards keep a short error tail plus log paths.
• Each shard CLI is launched in a fresh process session, and interrupt cleanup targets the process group to avoid orphaned descendants.
• Handoff digest generation and per-shard handoff file writes now run in parallel while preserving returned shard order.
• Contract tests were expanded to cover timeout-free script dispatch, log receiver behavior, compact main output, process-group lifecycle cleanup, and parallel handoff writing.

Verification performed after the update:

python3 -m unittest tests/test_preset_contract.py
Ran 21 tests in 0.261s
OK

The release tag/download URL in the original submission still points to v1.0.0. I can publish a patch release and update the issue metadata if the community listing review requires the downloadable archive to include these hardening changes.

[bigsmartben]

Updated submission details for the latest community-preset-ready release.

Preset ID: workflow-preset
Version: 1.0.3
Repository: https://github.com/bigsmartben/spec-kit-workflow-preset
Download URL: https://github.com/bigsmartben/spec-kit-workflow-preset/archive/refs/tags/v1.0.3.zip
License: MIT
Required Spec Kit version: >=0.8.10.dev0
Tags: planning, design, implementation, orchestration, handoff
Provides: 4 templates, 3 commands, 0 scripts

Validation completed:

• python3 -m unittest tests/test_preset_contract.py -> 36 tests OK
• JSON schema parse checks OK
• git diff --check OK
• specify preset add --dev /home/bigben/文档/github/spec-kit-workflow-preset OK
• specify preset add --from https://github.com/bigsmartben/spec-kit-workflow-preset/archive/refs/tags/v1.0.3.zip OK

Note: I briefly opened PR #2641 from the catalog branch, but the community flow should be issue-first. I will close that PR so this submission can proceed through this issue.

[bigsmartben]

Small clarification after the latest metadata update: v1.0.3 is now the intended review target for this preset submission.

Canonical submission assets:

• Repository: https://github.com/bigsmartben/spec-kit-workflow-preset
• Tag archive: https://github.com/bigsmartben/spec-kit-workflow-preset/archive/refs/tags/v1.0.3.zip
• Release: https://github.com/bigsmartben/spec-kit-workflow-preset/releases/tag/v1.0.3

The earlier catalog PRs (#2617 and #2641) are closed, so this issue remains the canonical review thread.